4 days ago - 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 and image size). To enable bytecode compilation, use the --compile-bytecode flag: ... Alternatively, you can set the UV_COMPILE_BYTECODE environment variable to ensure that all commands within the Dockerfile compile bytecode:

October 5, 2026 - RUN --mount=type=cache,target=/root/.cache/uv \ uv sync --frozen --no-install-project · When using cache mounts, set UV_LINK_MODE=copy to suppress warnings about cross-filesystem linking (uv falls back to copying automatically, but the warning is noisy): ... Add this alongside the other environment variables in your Dockerfile.

This means that even when a layer needs to be rebuilt, your package manager only fetches what's new or updated. This Dockerfile uses the following cache mount syntax: RUN --mount=type=cache,target=/root/.cache/uv \ uv sync --no-install-project --no-devCopy code

June 12, 2025 - RUN uv venv /opt/venv && uv pip install -r requirements.txt # OR RUN uv pip install --system · Losing UV’s speed benefits due to Docker layer caching: Docker caches image layers, but each RUN command is a new layer. Solution: Structure your Dockerfile to take advantage of caching.

# Installing separately from its dependencies allows optimal layer caching · COPY . /app · RUN --mount=type=cache,target=/root/.cache/uv \ uv sync --locked · · # Place executables in the environment at the front of the path · ENV PATH="/app/.venv/bin:$PATH" ·

This image runs the application in production mode. The standalone.Dockerfile example extends the multistage.Dockerfile example to use a managed Python interpreter in a multistage build instead of the system interpreter that comes with the base image.

August 6, 2026 - Anyways, if your application isn’t packaged for whatever reason: I have added inline notes how to adjust the Dockerfile. In a nutshell, instead of installing your application in the build step, you COPY it into the runtime container after COPYing /app over. Be careful to not overwrite /app. P.S. If you need more help with Docker, my friend Itamar Turner-Trauring has great resources for you. 2026-08-06: Share apt directories across builds. Switch to env variables where possible. 2024-11-12: Added a workaround for #9046: Use absolute paths for UV_PYTHON on uv 0.5.0+.

July 27, 2026 - After some research (and a fair bit of trial and error), here’s how I’m structuring my Dockerfile to make the most of UV in a robust, production-ready way. ... >FROM python:3.12-slim-bookworm AS builder >RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates >ADD https://astral.sh/uv/0.5.31/install.sh /uv-installer.sh >RUN sh /uv-installer.sh && rm /uv-installer.sh >ENV PATH="/root/.local/bin/:$PATH" >ENV UV_COMPILE_BYTECODE=1 >ENV UV_LINK_MODE=copy >WORKDIR /app >COPY pyproject.toml uv.lock ./ >RUN uv sync --frozen --no-install-project ># Run arbitrary Pytho

December 3, 2024 - To initialize the project, let’s start with a minimal Dockerfile. # docker/Dockerfile FROM python:3.13.0-slim ENV USER=uv-example-user \ PYTHONDONTWRITEBYTECODE=1 \ PYTHONUNBUFFERED=1 \ UV_PROJECT_ENVIRONMENT=/usr/local RUN apt-get update && apt-get install --no-install-recommends -y \ curl \ && apt-get clean \ && rm -rf /var/lib/apt/lists/* \ && useradd -m -s /bin/bash $USER COPY --from=ghcr.io/astral-sh/uv:0.5.5 /uv /uvx /bin/ ENV APP_DIR=/home/$USER/src WORKDIR $APP_DIR COPY src $APP_DIR ENV PYTHONPATH=$APP_DIR RUN chown -R "$USER":"$USER" $APP_DIR USER $USER CMD ["uvicorn", "main:app", "--host", "0.0.0.0"]

August 6, 2025 - When you add uv at the very beginning of your Dockerfile, you give Docker a stable, cacheable layer for your dependency installation process. Since dependencies change far less often than source code, this means faster rebuilds.

uv run effectively runs uv sync before each, meaning we always need to include --no-dev in any case where uv run is used or we'll end up installing the packages in each container or syncing the environment each time uv run is called.

July 27, 2025 - The pyproject.toml file is central ... pip and uv. In the project table we can see the project’s name, version, description, and dependencies. With the project initialized, we need to create a few additional files to structure our application and Docker build process. These include the Dockerfile for the multistage build, the main FastAPI application file (main.py), and an entrypoint file (__main__.py) for running the ...

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 .

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

December 14, 2024 - This may seem late in the game, but up till now only pyproject.toml and uv.lock changes would trigger a rebuild, so it's good that we have this extremely mutable artifact as late as possible. At this point we have our own code inside /app and all requirements in the /env folder on the system.

February 5, 2026 - A Dockerfile for python-base might look like this: 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.

December 22, 2024 - Here’s the dockerfile that I use to install packages with uv in Docker. Ensure that you pin your version of uv as breaking changes do occur! ... When you run python inside the container you should not need to active the virtual environment because we have added the virtual environment to the PATH.

Use dev images in build stages to run shell commands and then copy any necessary artifacts into the runtime stage. In addition, use Docker Debug to debug containers with no shell. Docker Hardened Images may have different entry points than images such as Docker Official Images. Use docker inspect to inspect entry points for Docker Hardened Images and update your Dockerfile if necessary. When using uv in a multi-stage build, ensure that the virtual environment created by uv is properly copied to your runtime stage.

2 weeks ago - This guide follows the patterns in uv’s Docker documentation. This is a two-stage build for a typical application. The uv version is an example, so pin the current one you use. # --- builder --- FROM python:3.14-slim AS builder COPY --from=ghcr.io/astral-sh/uv:0.13.6 /uv /uvx /bin/ ENV UV_COMPILE_BYTECODE=1 \ UV_LINK_MODE=copy \ UV_NO_DEV=1 WORKDIR /app # 1. Dependencies only: this layer is reused until the lockfile changes 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 # 2.