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

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add documentation for intermediate Docker layers in a workspace #16787

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
38 changes: 35 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,42 @@ _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:

- Copy all of the workspace member `pyproject.toml` files
- 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 \
--mount=type=bind,source=foo/pyproject.toml,target=foo/pyproject.toml \
--mount=type=bind,source=bar/pyproject.toml,target=bar/pyproject.toml \
uv sync --locked --no-install-workspace

ADD . /app

RUN --mount=type=cache,target=/root/.cache/uv \
uv sync --locked
Copy link
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
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
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
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.

```

!!! tip

Copying the workspace member `pyproject.toml` files is needed for `--locked` to assert that
the lockfile matches the contents of the `pyproject.toml`. The member `pyproject.toml` files can
be skipped by using `--frozen` during the workspace sync instead.

### Non-editable installs

Expand Down
Loading