Skip to content

Add documentation for intermediate Docker layers in a workspace #16787

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
zanieb merged 2 commits into from
Nov 24, 2025
+32 −3
Merged

Add documentation for intermediate Docker layers in a workspace #16787

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
693e73e
Add documentation for intermediate layers with a workspace
zanieb Nov 20, 2025
29fc564
Review
zanieb Nov 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 32 additions & 3 deletions docs/guides/integration/docker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -424,10 +424,39 @@ _contents_ are not copied into the image until the final `uv sync` command.

!!! tip

If you're using a [workspace](../../concepts/projects/workspaces.md), then use the
`--no-install-workspace` flag which excludes the project _and_ any workspace members.
If you want to remove additional, specific packages from the sync,
use `--no-install-package <name>`.

If you want to remove specific packages from the sync, use `--no-install-package <name>`.
#### Intermediate layers in workspaces

If you're using a [workspace](../../concepts/projects/workspaces.md), then a couple changes are
needed:

- Use `--frozen` instead of `--locked` during the initially sync.
- Use the `--no-install-workspace` flag which excludes the project _and_ any workspace members.

```dockerfile title="Dockerfile"
# Install uv
FROM python:3.12-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

WORKDIR /app

RUN --mount=type=cache,target=/root/.cache/uv \
--mount=type=bind,source=uv.lock,target=uv.lock \
--mount=type=bind,source=pyproject.toml,target=pyproject.toml \
uv sync --frozen --no-install-workspace

ADD . /app

RUN --mount=type=cache,target=/root/.cache/uv \
uv sync --locked
Copy link
Copy Markdown
Member

@charliermarsh charliermarsh Nov 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I would recommend --frozen here, isn't it much simpler? That's what we tend to do in our own Dockerfiles.

Copy link
Copy Markdown
Member Author

@zanieb zanieb Nov 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In what sense? --frozen here doesn't change anything because the whole workspace has been added already, it'd be up above where using --frozen instead of --locked makes things simpler.

I don't think we should recommend --frozen in general though, because I think --locked asserting that your uv.lock is not stale is meaningful and helpful.

I think it's fine to recommend --frozen above and rely on this subsequent --locked to catch a stale lock, but I worry that will also be confusing to people (i.e., I recommended exactly this in the issue and the user opted to do the additional mounts instead)

Copy link
Copy Markdown
Member

@charliermarsh charliermarsh Nov 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, I meant to comment on the line above. I personally find it unnecessary to enumerate all of the pyproject.toml files in the uv sync --no-install-workspace when you're doing a locked install here anyway? (But -- again personally -- I wouldn't use --locked in a Dockerfile, I think that validation should be done in CI.)

In pyx at least, we instead use --frozen for this install phase, but enumerate all the workspace members when we do the ADD (to minimize invalidation).

Copy link
Copy Markdown
Member Author

@zanieb zanieb Nov 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah... I'll change it.

```

uv cannot assert that the `uv.lock` file is up-to-date without each of the workspace member
`pyproject.toml` files, so we use `--frozen` instead of `--locked` to skip the check during the
initial sync. The next sync, after all the workspace members have been copied, can still use
`--locked` and will validate that the lockfile is correct for all workspace members.

### Non-editable installs

Expand Down
Loading