To run a uv command in an image, use one of the derived images, e.g.: docker run -it --rm astral/uv:bookworm-slim uv --version Copy · See the uv Docker integration guide⁠ for more details. See the available images documentation⁠ for a description of uv's Docker image tagging scheme.

1 week ago - In the context of a multi-stage Docker image, --no-editable can be used to include the project in the synced virtual environment from one stage, then copy the virtual environment alone (and not the source code) into the final image. ... # Install uv FROM python:3.12-slim AS builder COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/ # Use the system Python across both stages ENV UV_PYTHON_DOWNLOADS=0 # 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 --locked --no-install-project --no-editable # Copy the project into the intermediate image COPY .

An example project for using uv in Docker images, with a focus on best practices for developing with the project mounted in the local image.

An example of using uv in Docker images. Contribute to astral-sh/uv-docker-example development by creating an account on GitHub.

As with the distroless image, each derived image is published with uv version tags as ghcr.io/astral-sh/uv:{major}.{minor}.{patch}-{base} and ghcr.io/astral-sh/uv:{major}.{minor}-{base}, e.g., ghcr.io/astral-sh/uv:0.11.3-alpine. In addition, starting with 0.8 each derived image also sets UV_TOOL_BIN_DIR to /usr/local/bin to allow uv tool install to work as expected with the default user. For more details, see the GitHub Container page. Use one of the above images with uv pre-installed or install uv by copying the binary from the official distroless Docker image:

March 18, 2025 - Before we dive into pros, cons, and differences, let’s quickly describe each Dockerfile. An example of using a single stage with uv pre-installed. # Use a Python image with uv pre-installed FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim # Install the project into `/app` WORKDIR /app # Enable bytecode compilation ENV UV_COMPILE_BYTECODE=1 # Copy from the cache instead of linking since it's a mounted volume ENV UV_LINK_MODE=copy # Install the project's dependencies using the lockfile and settings 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 --no-dev # Then, add the rest of the project source code and install it ADD .

© 2026 Docker, Inc. All rights reserved. | Terms of Service | Subscription Service Agreement | Privacy | Legal

In the context of a multi-stage Docker image, --no-editable can be used to include the project in the synced virtual environment from one stage, then copy the virtual environment alone (and not the source code) into the final image. ... # Install uv FROM python:3.12-slim AS builder COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/ # Use the system Python across both stages ENV UV_PYTHON_DOWNLOADS=0 # 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 --locked --no-install-project --no-editable # Copy the project into the intermediate image COPY .

$ docker pull ghcr.io/astral-sh/uv:0.11.7-python3.9-trixie

astral · The official Docker image for uv, the Python package manager.

1 week ago - See our guide on using uv in Docker for more details. uv release artifacts can be downloaded directly from GitHub Releases. Each release page includes binaries for all supported platforms as well as instructions for using the standalone installer via github.com instead of astral.sh.

March 25, 2026 - This document describes the Docker image build system, image variants, and distribution mechanisms for `uv`. This covers how Docker images are built as part of the release pipeline and published to co

March 23, 2026 - Learn how to integrate uv with other software: Using in Docker images · Using with Jupyter notebooks · Using with marimo notebooks · Using with pre-commit · Using in GitHub Actions · Using in GitLab CI/CD · Installing PyTorch · Building a FastAPI application ·

September 24, 2024 - Starting with 0.3.0, Astral’s uv brought many great features, including support for cross-platform lock files uv.lock. Together with subsequent fixes, it has become Python’s finest workflow tool for my (non-scientific) use cases. Here’s how I build production-ready containers, as fast ...

June 1, 2025 - COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv · This approach uses Docker’s multi-stage capabilities to grab the uv binary without needing to install it through pip or other package managers.

February 5, 2026 - FROM linuxbase:latest # our customized Ubuntu ENV PATH=/venv/bin:$PATH ENV PATH=/root/.cargo/bin:$PATH # install uv RUN curl -LsSf https://astral.sh/uv/install.sh | sh # set up a virtual env to use for whatever app is destined for this container.

0.9.2-python3.14-alpine · © 2026 Docker, Inc. All rights reserved. | Terms of Service | Subscription Service Agreement | Privacy | Legal

See our guide on using uv in Docker for more details. uv release artifacts can be downloaded directly from GitHub Releases. Each release page includes binaries for all supported platforms as well as instructions for using the standalone installer via github.com instead of astral.sh.