Skip to content

Use uv sync --locked in Dockerfile templates per official uv Docker guidance#279

Merged
x merged 2 commits intomainfrom
x/uv-in-docker
Mar 4, 2026
Merged

Use uv sync --locked in Dockerfile templates per official uv Docker guidance#279
x merged 2 commits intomainfrom
x/uv-in-docker

Conversation

@x
Copy link
Contributor

@x x commented Mar 3, 2026

To Dockerfile-uv.j2 templates:

  • Replace uv pip install --system with uv sync --locked
  • Add two-stage dependency installation
  • cache mounts
  • UV_COMPILE_BYTECODE=1
  • .venv in path

These changes are all based on:
https://docs.astral.sh/uv/guides/integration/docker/

Greptile Summary

Migrates all 7 Dockerfile-uv.j2 templates from uv pip install --system to uv sync --locked, following the official uv Docker guidance. Also un-ignores uv.lock files in .gitignore so they can be committed (required by --locked).

  • Two-stage dependency install: Dependencies are installed first (--no-install-project), then the project code is copied and installed separately. This maximizes Docker layer caching — code changes no longer invalidate the dependency layer.
  • Build cache mounts: --mount=type=cache,target=/root/.cache/uv reuses the uv cache across builds, speeding up rebuilds.
  • UV_COMPILE_BYTECODE=1: Pre-compiles .pyc files at build time for faster container startup.
  • UV_LINK_MODE=copy: Ensures files are copied into the venv rather than hardlinked, which is the correct behavior inside containers.
  • .venv in PATH: Replaces the previous --system install approach with a proper virtual environment, adding it to PATH so python and uvicorn resolve correctly.
  • .gitignore updates: Removes uv.lock from ignore patterns in both root and examples/demos/procurement_agent/ so lockfiles can be committed to version control.

Confidence Score: 5/5

  • This PR is safe to merge — it follows well-documented uv best practices and all template changes are consistent.
  • All 7 Dockerfile templates are updated consistently with the same pattern. The changes directly follow official uv Docker guidance. The COPY paths are correct relative to the existing WORKDIR. The .gitignore changes correctly allow uv.lock to be committed, which is required by --locked. No functional regressions introduced — the temporal templates retain their tctl installation and the pre-existing PYTHONPATH difference is unchanged.
  • No files require special attention.

Important Files Changed

Filename Overview
src/agentex/lib/cli/templates/default/Dockerfile-uv.j2 Migrated from uv pip install --system to uv sync --locked with two-stage dependency install, cache mounts, bytecode compilation, and .venv in PATH. Correct and well-structured.
src/agentex/lib/cli/templates/default-langgraph/Dockerfile-uv.j2 Identical changes to default template — migrated to uv sync --locked pattern with proper layer caching.
src/agentex/lib/cli/templates/sync/Dockerfile-uv.j2 Identical changes to default template — migrated to uv sync --locked pattern with proper layer caching.
src/agentex/lib/cli/templates/sync-langgraph/Dockerfile-uv.j2 Identical changes to default template — migrated to uv sync --locked pattern with proper layer caching.
src/agentex/lib/cli/templates/sync-openai-agents/Dockerfile-uv.j2 Identical changes to default template — migrated to uv sync --locked pattern with proper layer caching.
src/agentex/lib/cli/templates/temporal/Dockerfile-uv.j2 Temporal variant migrated to uv sync --locked. Correctly retains tctl installation step. Missing PYTHONPATH=/app is a pre-existing difference from non-temporal templates.
src/agentex/lib/cli/templates/temporal-openai-agents/Dockerfile-uv.j2 Same as temporal template — correctly migrated with tctl step preserved.
.gitignore Removed examples/**/uv.lock from gitignore since uv.lock files must be committed for uv sync --locked to work.
examples/demos/procurement_agent/.gitignore Removed uv.lock from gitignore, consistent with the root .gitignore change.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["FROM python:3.12-slim + uv"] --> B["apt-get install system deps"]
    B --> C["Set ENV: UV_COMPILE_BYTECODE=1, UV_LINK_MODE=copy"]
    C --> D["WORKDIR /app/project"]
    D --> E["COPY pyproject.toml + uv.lock"]
    E --> F["uv sync --locked --no-install-project --no-dev\n(cached: deps layer)"]
    F --> G["COPY project/ code"]
    G --> H["uv sync --locked --no-dev\n(install project into venv)"]
    H --> I["ENV PATH=.venv/bin:$PATH"]
    I --> J["CMD uvicorn project.acp:acp"]

    style E fill:#e1f5fe
    style F fill:#b3e5fc
    style G fill:#e1f5fe
    style H fill:#b3e5fc
    style I fill:#c8e6c9
Loading

Last reviewed commit: 005dfec

…uidance

Replace `uv pip install --system` with `uv sync --locked` in all 7
Dockerfile-uv.j2 templates. This uses the uv.lock file for reproducible
builds, adds two-stage dependency installation for layer caching, BuildKit
cache mounts, UV_COMPILE_BYTECODE for faster startup, and virtualenv PATH.

Also remove uv.lock from existing .gitignore files that were blocking it.
@x x requested review from danielmillerp and smoreinis March 3, 2026 19:35
@x
Copy link
Contributor Author

x commented Mar 3, 2026

Tested with docker build and docker run against the docker-compose backend and things work as expected

@x x enabled auto-merge March 3, 2026 21:23
@x x merged commit b1f5ff8 into main Mar 4, 2026
50 of 54 checks passed
@x x deleted the x/uv-in-docker branch March 4, 2026 17:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants