Skip to content

Using uv in Docker#

Getting started#

Tip

Check out the uv-docker-example project for an example of best practices when using uv to build an application in Docker.

Running uv in a container#

A Docker image is published with a built version of uv available. To run a uv command in a container:

$ docker run ghcr.io/astral-sh/uv --help

Available images#

uv provides a distroless Docker image including the uv binary. The following tags are published:

  • uv:latest
  • uv:{major}.{minor}.{patch}, e.g., uv:0.4.10
  • uv:{major}.{minor}, e.g., uv:0.4 (the latest patch version)

In addition, uv publishes the following images:

  • Based on alpine:3.20:
    • uv:alpine
    • uv:alpine3.20
  • Based on debian:bookworm-slim:
    • uv:debian-slim
    • uv:bookworm-slim
  • Based on buildpack-deps:bookworm:
    • uv:debian
    • uv:bookworm
  • Based on python3.x-alpine:
    • uv:python3.12-alpine
    • uv:python3.11-alpine
    • uv:python3.10-alpine
    • uv:python3.9-alpine
    • uv:python3.8-alpine
  • Based on python3.x-bookworm:
    • uv:python3.12-bookworm
    • uv:python3.11-bookworm
    • uv:python3.10-bookworm
    • uv:python3.9-bookworm
    • uv:python3.8-bookworm
  • Based on python3.x-slim-bookworm:
    • uv:python3.12-bookworm-slim
    • uv:python3.11-bookworm-slim
    • uv:python3.10-bookworm-slim
    • uv:python3.9-bookworm-slim
    • uv:python3.8-bookworm-slim

As with the distroless image, each image is published with uv version tags as uv:{major}.{minor}.{patch}-{base} and uv:{major}.{minor}-{base}, e.g., uv:0.4.10-alpine.

For more details, see the GitHub Container page.

Installing uv#

Use one of the above images with uv pre-installed or install uv by copying the binary from the official distroless Docker image:

Dockerfile
FROM python:3.12-slim-bookworm
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv

Or, with the installer:

Dockerfile
FROM python:3.12-slim-bookworm

# The installer requires curl (and certificates) to download the release archive
RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates

# Download the latest installer
ADD https://astral.sh/uv/install.sh /uv-installer.sh

# Run the installer then remove it
RUN sh /uv-installer.sh && rm /uv-installer.sh

# Ensure the installed binary is on the `PATH`
ENV PATH="/root/.cargo/bin/:$PATH"

Note this requires curl to be available.

In either case, it is best practice to pin to a specific uv version, e.g., with:

COPY --from=ghcr.io/astral-sh/uv:0.4.10 /uv /bin/uv

Or, with the installer:

ADD https://astral.sh/uv/0.4.10/install.sh /uv-installer.sh

Installing a project#

If you're using uv to manage your project, you can copy it into the image and install it:

Dockerfile
# Copy the project into the image
ADD . /app

# Sync the project into a new environment, using the frozen lockfile
WORKDIR /app
RUN uv sync --frozen

Important

It is best practice to add .venv to a .dockerignore file in your repository to prevent it from being included in image builds. The project virtual environment is dependent on your local platform and should be created from scratch in the image.

Then, to start your application by default:

Dockerfile
# Presuming there is a `my_app` command provided by the project
CMD ["uv", "run", "my_app"]

Tip

It is best practice to use intermediate layers separating installation of dependencies and the project itself to improve Docker image build times.

See a complete example in the uv-docker-example project.

Using the environment#

Once the project is installed, you can either activate the project virtual environment by placing its binary directory at the front of the path:

Dockerfile
ENV PATH="/app/.venv/bin:$PATH"

Or, you can use uv run for any commands that require the environment:

Dockerfile
RUN uv run some_script.py

Tip

Alternatively, the UV_PROJECT_ENVIRONMENT setting can be set before syncing to install to the system Python environment and skip environment activation entirely.

Using installed tools#

To use installed tools, ensure the tool bin directory is on the path:

Dockerfile
ENV PATH=/root/.local/bin:$PATH
RUN uv tool install cowsay

$ docker run -it $(docker build -q .) /bin/bash -c "cowsay -t hello"
  _____
| hello |
  =====
     \
      \
        ^__^
        (oo)\_______
        (__)\       )\/\
            ||----w |
            ||     ||

Note

The tool bin directory's location can be determined by running the uv tool dir --bin command in the container.

Alternatively, it can be set to a constant location:

Dockerfile
ENV UV_TOOL_BIN_DIR=/opt/uv-bin/

Installing Python in musl-based images#

While uv installs a compatible Python version if there isn't one available in the image, uv does not yet support installing Python for musl-based distributions. For example, if you are using an Alpine Linux base image that doesn't have Python installed, you need to add it with the system package manager:

apk add --no-cache python3~=3.12

Developing in a container#

When developing, it's useful to mount the project directory into a container. With this setup, changes to the project can be immediately reflected in a containerized service without rebuilding the image. However, it is important not to include the project virtual environment (.venv) in the mount, because the virtual environment is platform specific and the one built for the image should be kept.

Mounting the project with docker run#

Bind mount the project (in the working directory) to /app while retaining the .venv directory with an anonymous volume:

$ docker run --rm --volume .:/app --volume /app/.venv [...]

Tip

The --rm flag is included to ensure the container and anonymous volume are cleaned up when the container exits.

See a complete example in the uv-docker-example project.

Configuring watch with docker compose#

When using Docker compose, more sophisticated tooling is available for container development. The watch option allows for greater granularity than is practical with a bind mount and supports triggering updates to the containerized service when files change.

Note

This feature requires Compose 2.22.0 which is bundled with Docker Desktop 4.24.

Configure watch in your Docker compose file to mount the project directory without syncing the project virtual environment and to rebuild the image when the configuration changes:

compose.yaml
services:
  example:
    build: .

    # ...

    develop:
      # Create a `watch` configuration to update the app
      #
      watch:
        # Sync the working directory with the `/app` directory in the container
        - action: sync
          path: .
          target: /app
          # Exclude the project virtual environment
          ignore:
            - .venv/

        # Rebuild the image on changes to the `pyproject.toml`
        - action: rebuild
          path: ./pyproject.toml

Then, run docker compose watch to run the container with the development setup.

See a complete example in the uv-docker-example project.

Optimizations#

Compiling bytecode#

Compiling Python source files to bytecode is typically desirable for production images as it tends to improve startup time (at the cost of increased installation time).

To enable bytecode compilation, use the --compile-bytecode flag:

Dockerfile
RUN uv sync --compile-bytecode

Alternatively, you can set the UV_COMPILE_BYTECODE environment variable to ensure that all commands within the Dockerfile compile bytecode:

Dockerfile
ENV UV_COMPILE_BYTECODE=1

Caching#

A cache mount can be used to improve performance across builds:

Dockerfile
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync

If you're not mounting the cache, image size can be reduced by using the --no-cache flag or setting UV_NO_CACHE.

Note

The cache directory's location can be determined by running the uv cache dir command in the container.

Alternatively, the cache can be set to a constant location:

Dockerfile
ENV UV_CACHE_DIR=/opt/uv-cache/

Intermediate layers#

If you're using uv to manage your project, you can improve build times by moving your transitive dependency installation into its own layer via the --no-install options.

uv sync --no-install-project will install the dependencies of the project but not the project itself. Since the project changes frequently, but its dependencies are generally static, this can be a big time saver.

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

# Change the working directory to the `app` directory
WORKDIR /app

# Install dependencies
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-project

# Copy the project into the image
ADD . /app

# Sync the project
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen

Note that the pyproject.toml is required to identify the project root and name, but the project contents are not copied into the image until the final uv sync command.

Tip

If you're using a workspace, then use the --no-install-workspace flag which excludes the project and any workspace members.

If you want to remove specific packages from the sync, use --no-install-package <name>.

Using uv temporarily#

If uv isn't needed in the final image, the binary can be mounted in each invocation:

Dockerfile
RUN --mount=from=ghcr.io/astral-sh/uv,source=/uv,target=/bin/uv \
    uv sync

Using the pip interface#

Installing a package#

The system Python environment is safe to use this context, since a container is already isolated. The --system flag can be used to install in the system environment:

Dockerfile
RUN uv pip install --system ruff

To use the system Python environment by default, set the UV_SYSTEM_PYTHON variable:

Dockerfile
ENV UV_SYSTEM_PYTHON=1

Alternatively, a virtual environment can be created and activated:

Dockerfile
RUN uv venv /opt/venv
# Use the virtual environment automatically
ENV VIRTUAL_ENV=/opt/venv
# Place entry points in the environment at the front of the path
ENV PATH="/opt/venv/bin:$PATH"

When using a virtual environment, the --system flag should be omitted from uv invocations:

Dockerfile
RUN uv pip install ruff

Installing requirements#

To install requirements files, copy them into the container:

Dockerfile
COPY requirements.txt .
RUN uv pip install -r requirements.txt

Installing a project#

When installing a project alongside requirements, it is best practice to separate copying the requirements from the rest of the source code. This allows the dependencies of the project (which do not change often) to be cached separately from the project itself (which changes very frequently).

Dockerfile
COPY pyproject.toml .
RUN uv pip install -r pyproject.toml
COPY . .
RUN uv pip install -e .