ymnik13/python-uv repository overview

⁠ymnik13/python-uv

Python base images with uv⁠ preinstalled and a role-based entrypoint, built for FastAPI / Celery / worker services.

Two flavours per version: a slim production image and a dev image with a build toolchain and a project scaffolder.

Published on Docker Hub⁠.

⁠Tags

latest / dev track 3.14. Pin the minor (3.14) in committed files; the full patch tag (3.14.7) is there when you need a frozen build.

Platforms: linux/amd64, linux/arm64.

Base: python:<version>-slim⁠.

⁠What's inside

Both images

• uv and uvx on PATH (static binaries, version pinned per build)
• a ready virtualenv at /opt/venv, first on PATH
• tini as PID 1 (reaps zombies — matters for Celery prefork and cron)
• gosu, cron, curl, ca-certificates, tzdata, libpq5
• non-root user app (1000:1000)
• the role-based entrypoint described below

-dev only

• build-essential, gcc, g++, make, pkg-config, libpq-dev, libffi-dev, libssl-dev
• git, wget, unzip, jq, less, procps, vim-tiny, openssh-client
• ruff preinstalled
• the dev-app helper script (project scaffolding, Node.js bootstrap)
• reload mode on by default (APP_RELOAD=1)

Approximate sizes: production ~77 MB compressed (~300 MB on disk), dev ~222 MB compressed (~865 MB on disk). The tag list above shows the compressed numbers; docker images shows the unpacked ones.

⁠Why the venv lives at /opt/venv

Not in /app/.venv. During development you bind-mount your project over /app, and a host .venv (wrong OS, wrong arch) would shadow the container's. Keeping it outside the mount makes bind mounts safe. UV_PROJECT_ENVIRONMENT points uv sync at it, so uv commands need no extra flags.

The trade-off: the venv lives in the container, not in your working tree. Mount a named volume at /opt/venv so it survives docker compose up recreations, and set RUN_UV_SYNC=1 to keep it in step with uv.lock. Both are shown below.

⁠Quick start

⁠Development

name: my-api

services:
  app:
    image: ymnik13/python-uv:3.14-dev
    container_name: my_api_app
    restart: unless-stopped
    working_dir: /app
    extra_hosts:
      - 'host.docker.internal:host-gateway'
    volumes:
      - .:/app
      - app-venv:/opt/venv     # keeps the venv across recreations
    env_file:
      - .env
    environment:
      CONTAINER_ROLE: app
      APP_MODULE: app.main:app
      APP_RELOAD: "1"
      APP_RELOAD_DIR: app      # watch only your code, not .git/docs
      RUN_UV_SYNC: "1"         # uv sync --frozen on every start
    ports:
      - "127.0.0.1:8000:8000"

volumes:
  app-venv:

docker compose up -d
docker compose exec app pytest -q
docker compose exec app ruff check .

⁠Production

Dockerfile

FROM ymnik13/python-uv:3.14

# Dependencies first: this layer survives code changes.
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev --no-install-project

COPY . .
RUN uv sync --frozen --no-dev

ENV CONTAINER_ROLE=app \
    APP_MODULE=app.main:app \
    APP_WORKERS=4

docker-compose.yml

x-app: &app
  image: my-api:prod
  restart: always
  env_file: [ .env ]
  depends_on:
    db:
      condition: service_healthy

services:
  app:
    <<: *app
    environment:
      CONTAINER_ROLE: app
      APP_WORKERS: 4
      WAIT_FOR: "db:5432"
    ports:
      - "127.0.0.1:8000:8000"

  worker:
    <<: *app
    environment:
      CONTAINER_ROLE: worker
      CELERY_APP: app.celery:celery_app
      CELERY_QUEUES: high,default,low
      CELERY_CONCURRENCY: 4

  beat:
    <<: *app
    environment:
      CONTAINER_ROLE: beat
      CELERY_APP: app.celery:celery_app

The application process runs as app (uid 1000), not root — the entrypoint drops privileges before exec'ing your server.

⁠Roles

Pick one with CONTAINER_ROLE (default app).

An explicit command always wins over the role:

docker run --rm ymnik13/python-uv:3.14 python -c 'print(1)'

⁠Environment variables

⁠General

⁠Startup hooks

Run in this order, before the role starts, as APP_USER:

⁠app role

⁠Celery roles

⁠Other roles

⁠Cron

cron starts with an empty environment, so the entrypoint snapshots the container env into /etc/container.env and the generated job sources it back:

scheduler:
  image: my-api:prod
  # The cron role keeps root - the daemon cannot run unprivileged. Only relevant
  # if you pinned `user: app` on the other services; the image starts as root and
  # drops privileges itself for every other role.
  environment:
    CONTAINER_ROLE: cron
    CRON_SCHEDULE: "*/5 * * * *"
    CRON_COMMAND: "python -m app.tasks.cleanup"

For several jobs, mount your own file over /etc/cron.d/app_cron:

* * * * * root . /etc/container.env; cd /app && python -m app.cron >> /proc/1/fd/1 2>&1

⁠Compiling from source

The production image has no compilers on purpose. If a dependency has no wheel for your platform, build it in the -dev image and copy the finished venv:

FROM ymnik13/python-uv:3.14-dev AS builder
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev

FROM ymnik13/python-uv:3.14
COPY --from=builder /opt/venv /opt/venv
COPY . .

⁠Notes

• .python-version — if your project pins a version different from the image tag, uv will refuse to continue: the image sets UV_PYTHON_DOWNLOADS=never, so it will not silently fetch another interpreter. Match the tag to the pin, or drop the file.
• Build cache — UV_CACHE_DIR is deliberately unset, so uv caches per user under $HOME. In your own Dockerfiles use a cache mount: RUN --mount=type=cache,target=/root/.cache/uv uv sync --frozen --no-dev.
• Host UID — the app user is 1000:1000. If your host user differs, either rebuild with --build-arg USER_UID=... --build-arg USER_GID=..., or set APP_USER=root.
• Postgres — libpq5 ships in both images, so psycopg works without the [binary] extra. libpq-dev (headers) is dev-only.

⁠dev-app (dev image only)

A helper for the boilerplate you would otherwise write by hand.

docker compose exec app dev-app          # interactive menu
docker compose exec app dev-app -h       # all commands
docker compose exec app dev-app info     # python / uv / venv versions

⁠Scaffolding a project

docker compose exec app dev-app py new --fastapi --name my-api

Writes a complete uv project into the working directory, then runs uv lock and uv sync:

pyproject.toml     project + dev group + ruff/pytest config
uv.lock            resolved
.python-version    matching the image
app/               main.py, settings.py (pydantic-settings)
tests/             a passing health test
Dockerfile         production build
docker-compose.yml dev stack (bind mount, venv volume, reload)
Makefile           up / down / sync / lint / test / migrate / shell
.env.example       .gitignore  .dockerignore  README.md

Templates: --fastapi (default), --worker (Celery), --minimal.

It refuses to run if pyproject.toml already exists. Files are chowned to HOST_UID:HOST_GID when set, otherwise to the current user:

environment:
  HOST_UID: ${HOST_UID:-1000}
  HOST_GID: ${HOST_GID:-1000}

⁠Other commands

dev-app py sync [args]     # uv sync (--frozen when uv.lock exists)
dev-app py add <pkg...>    # uv add
dev-app py lock            # uv lock
dev-app py lint            # ruff check .
dev-app py test [args]     # pytest
dev-app py shell           # REPL in the project venv

⁠Node.js

For projects with a frontend build step. Installs nvm, then Node, and links it into PATH so external calls work:

docker compose exec app dev-app node install 22   # no version → latest LTS
docker compose exec app node -v

Node is installed into the running container, so it has to be repeated after a recreate. Bake it in to make it permanent:

FROM ymnik13/python-uv:3.14-dev
RUN dev-app node install 22

⁠License

MIT.