DEV Community: Thomas Bury

Mastering Python Project Management with uv: Part 5 — advanced CI/CD Nox and uv.cli

Thomas Bury — Sat, 12 Apr 2025 19:22:34 +0000

Let's dive in advanced Python automation with nox, uv, and GitHub Actions — Part 5 of the Terminus Series

Building on Part 4, where we introduced fast, modern MLOps pipelines using uv, Docker, and CI/CD, this fifth installment focuses on automating your developer workflow using Nox — and why in 2025 it still reigns as one of the most flexible, transparent tools for Python-based projects.

This article walks through:

✅ What exactly Nox is and why it's still relevant in 2025
🧰 How we configure our noxfile in Terminus
🚀 How GitHub Actions can dynamically discover and run your nox sessions
⚖️ A brief but robust comparison of nox, Poe the Poet, and uv CLI
🏗️ Why Nox, despite the rise of CLI runners, still plays a crucial orchestration role

Absolutely! Here's a more comprehensive and pedantic rewrite of the section "Going Deeper with uv CLI Tools", structured to clearly guide the reader, explain motivations and use cases, and gracefully transition into the next section on nox:

Going Deeper with `uv` CLI Tools — Beyond `uv sync`

Up to this point, we've mostly used uv as a fast, lockfile-aware dependency resolver — replacing pip, pip-tools, or poetry for installing packages via uv sync. But that’s only scratching the surface.

In practice, uv is becoming a holistic developer toolchain manager — and in projects like Terminus, it eliminates the need for make, bash, or even task runners like poethepoet in many cases.

Let’s explore the full potential of uv as a modern CLI toolchain — both for local development and CI/CD pipelines.

`uv tool install` and `uv tool run`: Global CLI without Virtualenv Pain

While uv sync installs project-scoped dependencies into virtual environments, uv tool manages CLI tools globally, with user isolation:

uv tool install nox
uv tool run nox -- -s lint

This:

Installs nox (or any CLI tool) into a dedicated global environment at ~/.local/share/uv/tools
Keeps these tools separate from your project env or system Python
Ensures reproducibility across developer machines and CI — version-pinned via uv.lock if needed
Avoids venv activation, making developer onboarding zero-friction

In CI (as in Terminus), this means we don't need to activate a venv, use pipx, or worry about system-wide pip issues. We simply run:

uv tool install nox
uv tool run nox -- -s lint

Caching CLI Tools Between CI Runs

One performance advantage of uv tool is that CLI tools are cached globally in:

~/.local/share/uv/tools

By caching this directory in GitHub Actions:

- uses: actions/cache@v4
  with:
    path: ~/.local/share/uv/tools
    key: uv-tools-${{ runner.os }}-${{ hashFiles('pyproject.toml', '**/uv.lock') }}

You:

Avoid repeated downloads or rebuilds of CLI tools (e.g., nox, ruff, pytest)
Keep your build minimal and declarative — no surprise installs during jobs
Ensure clarity between “project dependencies” (uv sync) and “development tools” (uv tool)

Defining CLI Commands with `[tool.uv.cli]` in `pyproject.toml`

Just like poethepoet, uv lets you define custom developer commands directly in pyproject.toml — no extra dependencies needed.

[tool.uv.cli]
lint = "ruff check src"
format = "ruff format src"
test = "pytest tests/"

Run them with:

uv run lint
uv run test

This gives you the ergonomics of a task runner (like make or poe) without adding a new config language or runtime dependency.

You can think of it as task aliases bound to your dependency context, all managed by uv.

Recommendations:

Use uv run or [tool.uv.cli] for simple local dev flows: lint, serve, test, etc.
Use poethepoet if you need cross-platform make-like chaining with config in pyproject.toml
Use nox if you need session orchestration, multi-version testing, and dynamic CI compatibility

Now that we understand how uv and uv tool fit into modern Python projects, let’s look at how we use nox in Terminus to automate linting, testing, and Docker builds — in both local and CI pipelines.

Let’s dive into nox and dynamic CI automation.

What is `nox`, and Why Use It?

Nox is a Python automation tool designed to run sessions — isolated environments where you install dependencies and run scripts.

Unlike make, poe, or raw shell scripts:

Each session is run in a fresh virtual environment (by default)
You can target multiple Python versions per session
Dependencies can be scoped using a tool like uv, pip, or poetry
It’s Python-native: no new DSL, write Python functions

In Terminus, we use nox as the automation layer for tasks like linting and testing and can be extended to build the docs, clean up etc.

This makes Nox ideal for CI workflows — especially when the definition of what to run changes over time (via dynamic session discovery).

Terminus noxfile.py — Dissection

Let’s look at how Terminus’ noxfile.py enforces:

Single source of truth for Python version (extracted from pyproject.toml)
Group-based dependency installation via uv
Dev-friendly modular automation

📄 terminus/noxfile.py

# Parses Python version from pyproject.toml
# Sets uv as the backend
# Defines two nox sessions: lint

@nox.session(python=PYTHON_VERSION)
def lint(session):
    """Run Ruff linter and formatter checks."""
    session.run(
        "uv", "sync", "--group", LINT_GROUP,
        f"--python={session.python}",
        env={"UV_PROJECT_ENVIRONMENT": session.virtualenv.location},
        external=True
    )
    session.run("ruff", "check", CODE_DIR)
    session.run("ruff", "format", "--check", CODE_DIR)

Key takeaways:

Uses uv as venv backend for speed and lockfile support.
Reads the required Python version directly from pyproject.toml for full alignment across local + CI workflows.
Dependency isolation: installs only the lint group, not the full app stack.

Dynamic Matrix CI with GitHub Actions + Nox

Instead of hardcoding jobs, Terminus uses a modern matrix approach:

Step 1: Determine Python version and available nox sessions

jobs:
  generate-matrix:
    outputs:
      sessions: ${{ steps.set-matrix.outputs.sessions }}
      python-version: ${{ steps.get-python-version.outputs.version }}

Reads the Python version from pyproject.toml
Extracts nox sessions via nox --json -l and filters with jq

All this happens before the test matrix runs, so any added sessions automatically trigger in CI without manual YAML changes.

Step 2: Run each session in parallel

jobs:
  run-nox-sessions:
    strategy:
      matrix:
        session: ${{ fromJson(needs.generate-matrix.outputs.sessions) }}
    steps:
      - run: nox -s "${{ matrix.session }}"

Each session is isolated, fast, and reproducible — and uses uv as the environment and dependency manager.

Side-by-side Comparison: `nox` vs `poe` vs `uv cli`

Feature	`nox`	`poethepoet`	`uv` CLI
Language	Python-native	Custom `pyproject` syntax	Built-in to `uv`
Virtual Envs	Yes (isolated per session)	No (uses current env)	Optional via `uv venv`
CLI Task Syntax	`nox -s lint`	`poe lint`	`uv run ruff check src`
CI Friendly	✅ Matrix + Python version	⚠️ Mostly local convenience	✅ (if you know the commands)
Session Scoping	Per-group / per-version	Globally defined	Command-line scoped
Test Matrix Discovery	✅ (`--json`)	❌	❌
Modern Lock Support	✅ via `uv sync`	✅ via `uv` if integrated	✅

So when to use each?

Use poe or uv cli for small, script-oriented workflows and fast local CLI access.
Use nox when you:
- Need multiple Python versions
- Want true isolation per task
- Want to share automation across dev + CI reliably

Full Automation: From Code to Container

Once lint and test sessions pass, our CI continues to:

Build the image (multi-stage Docker build)
Authenticate to Docker Hub
Push image tagged by short SHA + latest

Defined here: .github/workflows/ci.yml

Final Thoughts

While new tools like uv and poethepoet offer impressive speed and simplicity, Nox remains an unparalleled orchestration layer in 2025 for teams needing:

Python version agility
Lockfile-aware sessions
Matrix-based CI pipelines

In Terminus, combining Nox with uv, GitHub Actions, and Docker gives us a maintainable and fully automated pipeline — fast, reproducible, and clean.

Codebase

🔗 View Terminus on GitHub

Includes:

noxfile.py
Dockerfile and docker-compose.yml
Full GitHub Actions workflow (ci.yml)
Example .env, src/, and tests/ (TODO)

Mastering Python Project Management with uv: Part 4 — CI/CD & Docker

Thomas Bury — Thu, 10 Apr 2025 09:42:07 +0000

Originally published on Medium

The Terminus Edition — Modern CI/CD and Deployment Workflows for LLM-Powered Apps

Context: LLM-Powered Apps Meet Modern Tooling

In Part 3 of the series, we explored how uv can simplify dependency management and improve MLOps for packaged Python applications. Now it’s time to take your project to production.

This part focuses on:

Dockerizing your app the modern way
Using docker-compose for local development
Automating CI/CD with GitHub Actions
Linting with ruff and running tests with uv run

We’ll use Terminus as the reference project—a FastAPI app that defines and validates user-defined topic-related terms using LLMs (Instructor + LiteLLM), Wikipedia, and Pydantic guardrails.

Production-Ready Docker Builds with `uv`: The Two-Stage Advantage

When containerizing a Python application, it’s tempting to throw everything into a single Dockerfile, install some packages, run your code, and call it a day.

Don’t.

Not if you care about:

⚡️ Build speed
🐍 Clean dependency separation
📦 Image size
🔒 Security

This is where the two-stage Docker build pattern shines — and paired with uv, the blazing-fast modern package manager, elevates Python Docker workflows to a new level of performance and simplicity.

Let’s dissect Terminus’ Dockerfile and understand what makes it tick.

Stage 1: Build Stage (a.k.a. “The Builder”)

FROM python:3.13-slim AS base

We start from a slim Python base — minimal but powerful. Here’s where the magic happens:

Install uv: uv is installed via pip, giving us a >10x faster resolver than pip or Poetry. It's designed for speed, reliability, and modern packaging workflows.
Install Build Dependencies: We temporarily install system packages like build-essential and curl — necessary for compiling Python wheels (think psycopg2, lxml, etc.). These are later purged to avoid bloating the final image.
Leverage Layer Caching:

COPY pyproject.toml uv.lock README.md ./

Only metadata is copied first. Why? Because Docker caches layers. If your dependencies haven’t changed, Docker will reuse the layer, dramatically speeding up future builds.

Install Dependencies:

RUN uv pip install --system . ...

Dependencies are installed directly into the system Python, not a virtual environment. This avoids virtualenv overhead, speeds up startup times, and is more memory efficient in production.

Copy Application Code: Source code is copied last so that frequent edits don’t bust the dependency cache. Clean separation of concerns!

Stage 2: Runtime Stage (a.k.a. “the user”)

FROM python:3.13-slim AS runtime

This stage is purposefully lean and minimal. It contains:

Only the runtime Python environment and dependencies
Your application source code
No compilers, no wheel caches, no source .pyc, no tools you don’t need in production

We copy:

COPY --from=base /usr/local /usr/localCOPY --from=base /app /app

This includes installed packages and the application itself — and nothing more.

We also define:

WORKDIR /appENV PYTHONPATH=/app/src

This ensures Python modules resolve properly when launched via FastAPI, CLI, or background tasks.

Result: A final image that is much smaller (sometimes up to 80%), loads faster, and is easier to secure.

In summary:

Smaller Images: no dev tools, no compilers, no cache = smaller size = faster pull times & fewer cloud resources.
Faster CI/CD: metadata-first copying + uv's resolver = lightning-fast builds and rebuilds.
Cleaner Production: no stray .pyc, no untracked dependencies, just the essentials.
Better Security: smaller attack surface; no dev tools left behind.
Reproducibility: uv.lock ensures the same dependency versions across machines and builds.
Speed: uv + ruff make linting and formatting lightning fast — perfect for CI/CD (see GitHub Actions below).

Tips for Getting It Right:

Always copy your lock file and pyproject.toml early to benefit from Docker layer caching.
Install your dependencies using uv pip install --system . — no need for venv or Poetry hacks.
Strip your build stage with apt-get purge and rm -rf to keep the final image lean.
Let Docker Compose or your runtime environment define the CMD, so the base image stays flexible and composable.

You can see this pattern fully implemented in Terminus’ GitHub repo along with the corresponding GitHub Actions workflow.

docker-compose with `uv`: Reproducibility meets velocity

Now that we’ve built a clean, layered Docker image using a two-stage DockerfileLet’s orchestrate it for local development using docker-compose. This is where uv starts to shine.

docker-compose lets you declaratively define how your app is built, configured, and run — across environments. Combined with uv, it gives us a fast, reproducible, and developer-friendly setup.

Let’s walk through the key pieces and highlight why uv changes the game:

Fast Iteration: Live Reloading with Mounted Volumes

volumes:  - ./src:/app/src

This mounts your local src/ directory directly inside the container. Any code changes you make on your machine are reflected immediately in the container — no rebuilds, no restarts (not meant for production).

Coupled with Uvicorn’s --reload flag, this enables hot-reloading of your FastAPI app during development — a productivity boost that feels native, even inside Docker.

Clean, Locked Environments with `uv`

Instead of relying on pip and requirements.txt, we use uv inside the container to:

Install dependencies from pyproject.toml, keeping the setup declarative and modern.
Enforce lockfile-based reproducibility using uv.lock
Run tools like ruff, pytest, or uvicorn without globally installing them.

Thanks to uv’s binary-first architecture, dependency resolution is blazingly fast, and the dev container is ready to go in seconds — no virtualenv juggling needed.

Environment Isolation Done Right

env_file:
  - .env
environment:
  - PYTHONPATH=/app/src
  - DATABASE_URL=sqlite:///data/terminus.db

Storing environment-specific settings (like API keys, model providers, and database paths) in a .env file.

uv respects these variables at runtime, and we explicitly set PYTHONPATH to ensure imports like from terminus.models import ... behave identically inside and outside Docker.

Health Checks for Early Failure Detection

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8000/docs"]

This tiny but powerful snippet tells Docker: “My app is alive if /docs responds.” If something breaks — like an LLM outage or a misconfigured .env — you’ll see it in docker ps right away.

Putting It All Together

command:
  - python
  - -m
  - uvicorn
  - src.terminus.app:app
  - --host
  - 0.0.0.0
  - --port
  - "8000"
  - --reload

Here, we use uvicorn to launch the app in development mode with live reload. By using python -m uvicorn, we make this command shell-agnostic and easier to port to other entrypoints (e.g., for Gunicorn in production).

Why `uv` Makes This Setup Better

In short, uv gives you modern dependency management that is:

Declarative (single source of truth in pyproject.toml)
Reproducible (locked versions across machines)
Fast (Rust-powered resolver is wicked quick)
Tool-friendly (no pipx, no venv gymnastics)

If you care about speed, reproducibility, and a frictionless dev environment, this pairing of uv with docker-compose is hard to beat.

GitHub Actions + `uv`: Clean CI/CD Pipelines

Your app is structured. Your Docker image is lean. Your development flow is fast.

Now it’s time to level up your continuous integration and delivery (CI/CD) with a GitHub Actions pipeline that’s just as modern as uv.

When done right, your CI should:

Lint for correctness and style
Run tests to catch regressions (shame on me, Terminus has no test suite yet)
Build and publish a Docker image (public or private Hub)
Use the same dependency versions as local development

Let’s break down what we’re doing and why uv makes it not only possible but elegant.

Lint and Validate (the fast way)

You don’t want broken code, and you want to know why it’s broken as early as possible.

That’s where Ruff comes in — an ultra-fast Python linter and formatter that’s written in Rust and integrates perfectly with uv.

- name: ✨ Lint with Ruff
  run: |
    uv run ruff check src
    uv run ruff format --check src

This runs two critical checks:

ruff check: finds bugs, code smells, and style violations.
ruff format --check: enforces formatting, CI-friendly (it fails if formatting isn’t followed).

Why this is great:

Runs in seconds
Uses the exact version of Ruff locked in pyproject.toml
Zero global installs — all inside the uv runtime

Test, Reproducibly

Assuming you’ve defined your test suite (e.g., with pytest or httpx for API tests), running it is a breeze:

- name: ✅ Run tests
  run: uv run pytest tests/

Why we love this:

Tests run in a clean, ephemeral environment (not your laptop!)
Always use the same versions of pytest, httpx, etc.
Optional: You can mock LLM calls or run against a test .env file for safe validation

The `uv sync` secret sauce

Before linting or testing, we install all dependencies:

- name: 📦 Install dependencies
  run: uv sync --dev

This single line:

Resolves and installs all production + development dependencies (Ruff, Pytest, etc.)
Uses the exact versions from your uv.lock
Skips virtualenvs and pip install . nonsense
Guarantees your CI runs exactly like your local dev container or machine

Build and Push a Docker Image

In a separate job (build-and-push-docker), we only trigger the Docker build after tests pass — because shipping broken containers helps no one.

We use docker/metadata-action to auto-generate tags like latest and a short Git SHA, and push the image to Docker Hub using your GitHub repository secrets.

images: ${{ secrets.DOCKERHUB_USERNAME }}/terminus
tags: |
  type=sha,format=short
  type=raw,value=latest

Want reproducibility and traceability? Use the SHA-based tag to pin an image to a commit forever.

Why `uv` Makes GitHub Actions Better

With uv, your GitHub Actions become:

Faster (no dependency juggling)
Reproducible (locked versions, always)
Cleaner (no extra YAML for managing Python tools)
More secure (no extra tools needed outside the uv runtime)

Publishing to Docker Hub — the Right Way

Once our application is linted, tested, and deemed production-ready, the final piece is building and pushing a Docker image to a registry. In this case: Docker Hub.

But we’re not just pushing any image. We’re pushing a reproducible, lightweight, and well-tagged artifact — built with uv, orchestrated by GitHub Actions.

Authenticate Securely (no credentials in sight)

Instead of hardcoding usernames or passwords (a security anti-pattern), we use GitHub repository secrets:

with:
  username: ${{ secrets.DOCKERHUB_USERNAME }}
  password: ${{ secrets.DOCKERHUB_TOKEN }}

These should be added in your repo under: Settings → Secrets and variables → Actions

You’ll need:

DOCKERHUB_USERNAME
DOCKERHUB_TOKEN (Docker Hub → Account Settings → Security → New Access Token)

These secrets never appear in logs

They auto-expire if you revoke them

They protect your pipeline from leakage

Auto-Generate Metadata and Tags

Instead of manually tagging your Docker images (error-prone and easy to forget), we use the docker/metadata-action to auto-tag based on Git info:

- uses: docker/metadata-action@v5
  with:
    images: ${{ secrets.DOCKERHUB_USERNAME }}/terminus
    tags: |
      type=sha,format=short        # Tag image with commit SHA (e.g., terminus:abc1234)
      type=raw,value=latest        # Also push as "latest"

This helps:

Traceability: Every pushed image is linked to a commit.
Convenience: :latest is available for local dev and quick pull.
Automation: No human errors in manual tagging.

Build Once, reuse always

Thanks to Docker BuildKit and layer caching via GitHub Actions:

cache-from: type=gha
cache-to: type=gha,mode=max

you get:

Faster builds (because unchanged layers are reused)
Lower CI costs (fewer image pulls/uploads)
Deterministic environments (same code = same image)

The build is based on your two-stage Dockerfile (explained above), which ensures:

Minimal attack surface (no dev tools in final image)
Fast cold starts (no bloat, clean dependencies)
uv is used inside the image too — so the containerized app benefits from the same ultra-fast resolution and install.

Push to Docker Hub

Finally, the docker/build-push-action does the actual build & publish:

- uses: docker/build-push-action@v6
  with:
    context: .
    push: true
    tags: ${{ steps.meta.outputs.tags }}

Once this step is completed, your image is:

Built with locked uv dependencies
Tagged with Git commit + latest
Published to Docker Hub, ready to be docker pulled anywhere

This step finalizes the loop of build → validate → ship — with every part driven by uv's speed and consistency and GitHub Actions' automation.

Let’s wrap up this build-and-deploy journey by zooming out and synthesizing everything we’ve accomplished.

What We’ve Built — A Fast, Clean, and Reproducible CI/CD Pipeline with `uv`

Let’s step back and admire the simplicity and power of the DevOps pipeline we’ve just assembled. What started as a FastAPI app Terminus is now a fully containerized, continuously validated, and registry-published service — all thanks to a few strategic tools and good practices.

Combining all the steps in .github/workflows/ci.yml

name: Terminus CI/CD

on:
  push:
    branches: [main]
    # trigger on tags for versioned releases
    # tags: ['v*.*.*']
  pull_request:
    branches: [main]

permissions:
  contents: read

env:
  PYTHON_VERSION: '3.13'

jobs:
  lint-and-test:
    name: Lint & Test
    runs-on: ubuntu-latest
    steps:
      - name: ⬇️ Checkout Code
        uses: actions/checkout@v4

      - name: 🐍 Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ env.PYTHON_VERSION }}

      - name: 📦 Install uv
        uses: astral-sh/setup-uv@v5

      - name: 🧠 Restore uv cache
        id: cache-uv
        uses: actions/cache@v4
        with:
          path: ~/.cache/uv
          key: uv-${{ runner.os }}-${{ hashFiles('pyproject.toml', 'uv.lock') }}
          restore-keys: |
            uv-${{ runner.os }}-

      - name: 📦 Install dependencies (lint)
        run: uv sync --group lint

      - name: ✨ Lint with Ruff
        run: |
          uv run ruff check src
          uv run ruff format --check src
    # Shame, no tests yet
    #   - name: ✅ Run tests
    #     run: uv run pytest tests/
    #     continue-on-error: true  # Make strict if critical

  build-and-push-docker:
    name: Build & Push Docker Image
    runs-on: ubuntu-latest
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    needs: lint-and-test
    permissions:
      contents: read

    steps:
      - name: ⬇️ Checkout Code
        uses: actions/checkout@v4

      - name: 🐳 Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: 🏷️ Docker Metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ secrets.DOCKERHUB_USERNAME }}/terminus
          tags: |
            type=sha,format=short
            type=raw,value=latest

      - name: 🔑 Log in to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: 🏗️ Build and Push Docker Image
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

Here’s what makes this pipeline shine:

`uv`: the dependency backbone

Lightning-fast resolution and install compared to pip + venv.
Lockfile (uv.lock) ensures reproducibility across environments (local, CI, Docker).
Single source of truth for runtime and dev dependencies via pyproject.toml.

Whether you’re syncing a new dev machine or building production containers, you run the same thing: uv sync.

Docker, the fast way

Two-stage build keeps dev tools and build dependencies out of the final image.
Uses uv to install directly into system Python, skipping venv overhead.
The final image is minimal, fast, and portable — optimized for cloud environments or edge deployment.

A clean image = smaller surface = faster startup = happier users.

GitHub Actions, but smarter

Separate stages for linting, testing, and deployment improve clarity and feedback loops.
Linting with ruff, testing with pytest, and building with docker — all run via uv, ensuring dev/prod parity.
Docker Hub publishing happens only when tests pass and only on the main branch — the golden rule of CI.

Bonus: Caching is used everywhere (Python deps, Docker layers), slashing build times in half.

This entire loop is automated, reproducible, and frictionless. As long as your code is clean and your tests pass, your FastAPI service gets linted, tested, containerized, and published — all without touching your laptop.

Closing Thoughts

In the Python world, where dependency hell, slow builds, and bloated containers are all too familiar, this stack — uv, Docker multi-stage builds, ruff, and GitHub Actions offer a modern antidote.

Whether you’re working on internal tools, ML APIs, or full-fledged SaaS backends, the benefits are clear:

Faster iteration
Safer builds
Simpler team onboarding
Reproducibility across the board

What’s next?

Is that it? Not quite! We can further enhance our local and global CI/CD workflow. In the next installment, we’ll explore how to integrate tools like uv (via its CLI or external CLIs like Poethepoet) and nox to create an even more robust GitHub Actions pipeline. Stay tuned for the next episode!

Happy shipping 🚀

Mastering Python Project Management with uv: Part 3 — MLops

Thomas Bury — Thu, 10 Apr 2025 09:25:27 +0000

Tired of waiting for pip? UV cuts dependency hell from coffee-break to blink-speed. Here's how I use it for MLOps—and why you should too.

🔗 Originally published on Medium. Shared here because dev.to folks know good tooling when they see it!

TL;DR (What’s In This Guide)

🚀 UV is like pip on steroids: Installs Python deps 10x faster than Poetry.
🔒 Lockfiles that work: No more "works on my machine" nonsense.
🐳 Docker magic: Build slim images without the headache.
🤖 CI/CD simplified: GitHub Actions that don’t make you want to cry.
👉 Try it now: mlops-uv

"why UV over Poetry/Pipenv/that-cool-tool-I-saw-on-HN?" Glad you asked. Let’s get hands-on.

How to use this guide

The supporting repo: mlops-uv

Build the project from scratch by manually setting up the structure and copy-pasting the provided code base (src and tests folders).
Clone the repository, install dependencies using the command uv sync\, and run the commands explained below directly to:

Execute the test suite
Build the Docker image
Modify and test GitHub Actions

Introduction

MLOps (Machine Learning Operations) is all about bringing DevOps principles into machine learning, making model deployment, versioning, and monitoring more efficient. However, managing dependencies, ensuring reproducibility, and streamlining deployments can be a major headache for ML/DS teams.

That’s where UV comes in — a fast, modern package manager that simplifies dependency management, build processes, and CI/CD for Python projects.

In this article, we’ll explore how UV can enhance MLOps workflows through AceBet, a mock-up FastAPI app that predicts the winner of an ATP match (for demonstration purposes only — don’t bet your savings on it!). We’ll cover:

Setting up a UV-based MLOps project
Managing dependencies and lockfiles
Automating CI/CD with GitHub Actions
Building and deploying with Docker

Let’s dive in!

Make sure to read:

for a smoother reading of the part 3.

📦 Initializing an MLOps Project with UV

When working on an MLOps project, structuring your codebase properly is crucial. We’ll start by setting up a packaged application using UV:

uv init --package acebet

A packaged application follows the src-based structure, where the source code is contained within a dedicated package directory (src/acebet). This approach is beneficial for:

✅ Large applications with multiple modules

✅ Projects that need to be distributed (e.g., PyPI packages, CLI tools)

✅ Better namespace isolation, preventing import conflicts

✅ Improved testability and modularity

example-pkg/
├── src/
│   ├── example_pkg/
│   │   ├── __init__.py
│   │   ├── module.py
│   │   └── utils.py
├── tests/
│   ├── test_module.py
├── pyproject.toml
└── README.md

This structure ensures:

✔ Encapsulation: The application is a proper Python package, avoiding accidental name conflicts.

✔ Reusability: Can be installed via pip install . or published to PyPI.

✔ Cleaner Imports: Enforces absolute imports (from example_pkg.utils import foo) instead of relative imports.

✔ Better CI/CD Support: Easier to package and distribute in Docker, PyPI, or GitHub Actions.

👉 For quick scripts or internal projects? Use a regular application.

👉 For scalable, maintainable, and deployable projects? Use a packaged application.

In our case, we will re-use AceBet, a simple FastAPI application following basic MLops principles. Including several modules for preparing the data, training the model, predicting and defining the endpoints, and a test suite.

A packaged app is therefore the best choice (and will be for anything else than POC)

🔧 Managing Dependencies with UV

Installing Core Dependencies

Once your project is initialized, install the necessary dependencies for developing AceBet, including FastAPI and machine learning libraries like Scikit-learn:

uv add fastapi scikit-learn pandas lightgbm

and any other packages required for the application to run properly. UV will take care of the resolution of the needed versions.

Creating a Lockfile for Reproducibility

One of UV’s key advantages is ensuring dependency reproducibility with a lockfile. This guarantees that all environments (local, staging, production) use the same dependency versions.

Once you are satisfied with the first version of the code base, generate a lockfile:

uv lock

Or, if you want to sync all dependencies in one go:

uv sync

This process ensures that dependency versions remain consistent across different environments — an essential practice in MLOps.

🛠 Adding Testing Dependencies & Running Tests

In MLOps, testing is just as important as model accuracy. UV provides 3 different and very convenient ways to run tests or use tools (a tool is usually a Python CLI such as pytest):

If you need a tool as part of your Python project, add it as a dependency (uv add --dev), they will be listed in the pyproject.toml as using other project managers.
If you only need to run a tool occasionally, execute it with uvx.
If you need a tool persistently in your system or Docker, install it using uv tool install.

You can add testing libraries using:

uv add --dev pytest

These dependencies will then be distributed as development dependencies with your application distribution.

A final piece of advice on how to choose the method:

The pyproject.toml should explicitly list all required dependencies for reliable test suite distribution, guaranteeing that developers use the same versions. We opt for the uv add --dev method, but the uv tool install will come in handy for Docker.

🚀 Automating CI/CD with GitHub Actions

Now that our application is running and tested properly, we want to ensure integrity if new commits are merged to the main branch.

A robust CI/CD pipeline ensures your models and applications are always production-ready. With UV, setting up GitHub Actions is straightforward.

Astral provides a GitHub Actions workflow that installs dependencies and runs tests automatically on every push to the main branch. A simple example would be running the test suite for each new commit on the main branch:

name: Testing
on:
  push:
    branches:
      - "main"
jobs:
  uv-example:
    name: Python
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install UV
        uses: astral-sh/setup-uv@v5
      - name: Install the project
        run: uv sync --all-extras --dev
      - name: Run tests
        run: uv run pytest tests

This workflow:

✅ Installs UV

✅ Syncs dependencies

✅ Runs unit tests using Pytest

You can refine and add a Python matrix, and further sophistication

🐳 Building a Docker Image with UV

A well-built Docker image simplifies deployment and ensures your application runs consistently in any environment. UV makes it easy to containerize an application.

Here’s a basic Dockerfile to containerize AceBet:

FROM python:3.12-slim

# Install UV
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

# Copy the application into the container
COPY . /app

# Set working directory
WORKDIR /app

# Install dependencies
RUN uv sync --frozen --no-cache

# Run the FastAPI app
CMD ["/app/.venv/bin/fastapi", "run", "src/acebet/app/main.py", "--port", "80", "--host", "0.0.0.0"]

For production-ready builds, use a multi-stage Docker build to keep the final image lightweight.

🌟 Why UV for MLOps?

🎯 Conclusion

By integrating UV into your MLOps workflow, you get a fast, reproducible, and efficient setup for managing dependencies, testing, and deployment.

With AceBet, we demonstrated how to:

✔️ Initialize a structured UV project

✔️ Manage dependencies & lockfiles

✔️ Automate testing with GitHub Actions

✔️ Build Docker images for deployment

If you’re working with Python-based MLOps projects, give UV a try — it might just replace Pip and Poetry in your workflow! 🚀

Mastering Python Project Management with uv: Part 2 – Deep Dives and Advanced Use

Thomas Bury — Sun, 06 Oct 2024 08:00:01 +0000

Welcome back! If you haven’t checked out Part 1, now’s the time to do so. We covered how uv simplifies managing dependencies, creating virtual environments, Python versions, and inline metadata. Now, let's go deeper into the magic of uv and explore its advanced features that can take Python development to the next level.

🛠 Updated on 23rd Feb 2025

This article has been revised based on valuable feedback from readers, thank you all!

1. Managing Dependencies with `pyproject.toml`

In Part 1, we introduced adding dependencies using uv. Let's expand on how uv integrates seamlessly with pyproject.toml, the standardized configuration file for Python projects.

Adding Dependencies with `uv add`

When you add a dependency using uv add, it updates your pyproject.toml file accordingly:

uv add fastapi

This command modifies your pyproject.toml to include:

[project]
name = "your_project_name"
version = "0.1.0"
dependencies = [
    "fastapi>=0.68,<1.0",
]

This makes your dependencies explicit and your project easily shareable with others. Whenever you or someone else clones your project, simply running uv will install the same packages listed.

Version Constraints: `>=` vs. `==`

It’s advisable to use version ranges (e.g., >=0.68,<1.0) rather than strict pinning (==0.68). This approach allows for compatibility with newer, non-breaking versions, ensuring your project remains up-to-date without unexpected disruptions. Strict pinning can lead to dependency conflicts and hinder the integration of security patches or performance improvements.

Optional Dependencies and Dependency Groups

uv supports the standardized optional-dependencies and dependency-groups as per the latest PEPs:

[project.optional-dependencies]
dev = ["pytest>=6.0", "black"]

[tool.uv.dependency-groups.docs]
dependencies = ["sphinx>=4.0"]
optional = true

To install these groups, use:

uv add --group dev <DEV_PACKAGE_01> <DEV_PACKAGE_02>
uv add --group docs <DOCS_PACKAGE_01> <DOCS_PACKAGE_02> <DOCS_PACKAGE_03>

for development dependencies and documentation dependencies.

2. Locking Dependencies with the `uv.lock` File

Whenever you add or update dependencies using uv, it doesn’t just modify your pyproject.toml file. uv also creates a uv.lock file. Why is this important?

Precise Versioning: The uv.lock file locks in the exact versions of all dependencies and their transitive dependencies (packages that your dependencies rely on).
Reproducible Environments: Whether it’s you coming back to a project after a break or a colleague cloning your repo, running uv will install the exact versions specified in the uv.lock file.

The result? A consistent, reliable environment that eliminates the “it works on my machine” problem.

3. Managing Tools: Global vs. Project-Specific

In Part 1, we discussed how uv makes it easy to install CLI tools. Now, let’s break down how uv distinguishes between global and project-specific tools.

Installing Global Tools

Installing a tool globally with uv is simple:

uv tool install black

This makes black available across all your projects but keeps it in its isolated virtual environment, avoiding system-wide conflicts.

Project-Specific Tools

If you need a tool for a specific project, add it directly as a dependency:

uv add --group dev ruff

This keeps the tool local to your project and listed in your pyproject.toml. Your other projects remain unaffected, allowing for isolated development environments.

Running Tools Ephemerally with `uvx`

For quick, one-off tool usage without permanently installing it, uvx is your friend:

uvx black my_script.py

This runs black within a temporary virtual environment and then cleans up afterward.

4. Creating & Using Virtual Environments the Right Way

Making Virtual Environments Easy

In Part 1, we explained how uv defaults to using virtual environments for all package installations. Here’s a quick recap:

uv venv

This command creates a .venv directory in your project. If you want to use a custom directory or Python version:

uv venv my_venv - python 3.11

You can then activate your virtual environment as you normally would:

$ .venv/Scripts/activate

Automatic Environment Detection

Whenever you work on a project managed by uv, the tool will automatically detect and use the appropriate virtual environment without any additional setup. No need to worry about manually activating or deactivating environments.

5. `uv` and Existing Environments

Already using another environment manager like conda? No problem. uv is built to play nicely with external virtual environments.

Automatic Environment Detection & Integration

When you use uv pip install or uv add, uv searches for existing virtual environments:

Activated environments (e.g., $VIRTUAL_ENV or $CONDA_PREFIX).
A .venv directory in your current project.

If uv doesn’t find a virtual environment, it will prompt you to create one to keep your environment clean and isolated.

6. Using Alternative Package Indexes and Authentication

While uv defaults to the official Python Package Index (PyPI), it supports alternative indexes, which often require authentication.

Configuring Alternative Indexes

Set an alternative index URL:

export UV_INDEX=https://example.com/simple

Authentication Using Environment Variables

For indexes requiring authentication, provide credentials via environment variables. For instance, with Azure Artifacts:

export UV_INDEX=https://username:$ADO_PAT@pkgs.dev.azure.com/organization/project/_packaging/feedName/pypi/simple/

Replace $ADO_PAT with your Personal Access Token. Refer to the official uv documentation for detailed instructions on various services.

7. Permanent Configuration

To avoid setting environment variables repeatedly, configure uv persistently.

Within a project, add the index URL to pyproject.toml:

[tool.uv]
index = [
  { url = "https://example.com/simple", default = true }
]

Alternatively, use uv.toml (preferred for non-Python-specific configurations):

[[index]]
url = "https://example.com/simple"
default = true

Precedence Order:

uv.toml overrides pyproject.toml if both exist in the same directory.
Project-level settings override user-level settings, which override system-level settings.
Environment variables take priority over all configuration files.
Use uv --no-config to temporarily ignore all configurations.

8. Types of Projects and Build System Options

uv supports multiple project types, each with different build system configurations. Selecting the right configuration depends on your project's packaging and distribution needs.

Project Type	Description	Example `pyproject.toml` Config
Standard Python Project	Uses `setuptools` for traditional package builds. Ideal for legacy and widely adopted setups.	`[build-system] requires = ["setuptools", "wheel"]`
PEP 517 Build Backend	Defines a custom backend like `hatchling`, `poetry`, or `flit`. Recommended for modern Python packaging.	`[build-system] requires = ["hatchling"]`
Workspace (Multi-Package)	A single repository containing multiple projects. Useful for monorepos and modular architectures.	`[tool.uv] workspace = true`
Non-Build Projects	Scripts or tool configurations that do not require packaging. Used for CLI utilities and personal projects.	No `[build-system]` section needed

🔹 Best Practice:

For new projects, use hatchling or flit instead of setuptools, as they align with modern Python packaging standards.

What’s Next?

✔ New to uv? Start with Part 1.

✔ Want more details? Check out the official uv documentation.

💬 Have you tried uv yet? Share your experience and questions in the comments! 🐍✨

Mastering Python Project Management with UV (Part 1): It’s Time to Ditch Poetry

Thomas Bury — Sun, 29 Sep 2024 14:38:21 +0000

🛠 Updated on 23rd Feb 2025
This article has been revised based on valuable feedback from readers, thank you all!

Are you tired of juggling multiple tools like pip, virtualenv, conda, poetry, and pyenv just to keep your Python environments and dependencies in check? You’re not alone! Managing Python projects can feel like a headache, especially with all the different package managers and tools you have to wrangle.

Enter `uv` – The Universal Virtualenv

Think of uv as a one-stop-shop package manager designed to streamline and speed up your Python development process.

A Little Backstory

uv draws its inspiration from Rye, another modern packaging manager, to unify the best features of pip, pip-tools, pyenv, virtualenv, and poetry. Built using Rust, uv is not just fast but highly efficient, simplifying everything from managing dependencies to creating virtual environments.

The Aim of `uv`

In a nutshell, uv is about consolidation. Why switch between multiple tools when you can have one unified experience? It aims to remove the friction from Python development, offering you a more consistent and faster way to manage your projects. And it’s also blazing fast! That opens new doors for dynamic management.

1. Portable Code with Inline Script Metadata

Let’s Talk Dependencies

One of the most exciting features of uv is the ability to add dependencies directly within your Python script. Imagine you have a simple script like this:

# app.py
import requests
from rich.pretty import pprint

response = requests.get("https://peps.python.org/api/peps.json")
data = response.json()
pprint([(k, v["title"]) for k, v in data.items()][:10])

Running this script usually means setting up a virtual environment and installing dependencies manually. With uv, you can embed all your dependencies directly into the script, making it self-contained and shareable:

uv add --script app.py 'requests<3' 'rich'

Automatic Metadata Generation

This adds metadata to the script file:

# app.py
# /// script
# dependencies = [
#   "requests<3",
#   "rich",
# ]
# ///
import requests
from rich.pretty import pprint

response = requests.get("https://peps.python.org/api/peps.json")
data = response.json()
pprint([(k, v["title"]) for k, v in data.items()][:10])

And that’s it! You can share this file with someone else, and they can simply run:

uv run app.py

And voilà — no external setup required! All thanks to uv’s speed and efficiency.

2. Creating and Managing Virtual Environments

Getting Started with Virtual Environments

By default, uv requires packages to be installed within virtual environments to keep your system clean and avoid conflicts between different projects. Creating a virtual environment with uv is simple:

uv venv

This will create a .venv directory containing the isolated environment. If you want to specify a custom directory or Python version, you can do:

uv venv my_env --python 3.9

The environment is ready to use, and uv will detect it automatically for all your commands, like installing packages or running scripts.

When to Use `uv add` vs. `uv pip install`

✅ Use `uv add`

When you want to add dependencies to your project’s pyproject.toml file. This is best when you are developing a project and want to keep track of all dependencies.

uv add fastapi

This will update your pyproject.toml and lock the version in uv.lock.

✅ Use `uv pip install`

When you want to install packages for quick use without modifying the project file or for global tools where you don’t need to track them in a pyproject.toml.

uv pip install requests

Choosing the right command ensures your project is properly managed and easy to share or deploy.

3. Lock Versions for Reproducibility

Ever Had Your Code Break Due to Updates?

We’ve all been there — your code works today, then breaks tomorrow because a package gets updated. With uv, you can prevent this by locking package versions to ensure consistency and reproducibility:

[tool.uv]
exclude-newer = "2023-10-16T00:00:00Z"

This way, even if new versions of your dependencies come out, your project remains stable. Perfect for long-term projects where you can’t afford surprises!

4. Managing Python Versions

Different Projects, Different Python Versions? No Problem!

Many developers work on multiple projects that require different Python versions. uv makes switching versions as easy as:

uv python install 3.8 3.9 3.10

Once the versions are installed, switching between them is seamless:

uv run --python 3.10 app.py

And if you want to lock a specific version for a project:

uv python pin 3.9

No more juggling pyenv commands — uv handles all the heavy lifting for you.

5. Say Goodbye to `pip` Hassles

It’s `pip` — but Faster and Better

uv provides a pip-like experience, but with turbocharged performance. Installing packages is straightforward:

uv pip install flask

Need to add optional dependencies or install directly from a GitHub repo? No sweat:

uv pip install 'torch>=1.10.0' "git+https://github.com/astral-sh/ruff"

No more waiting around for slow installations — uv gets the job done fast and effectively.

6. Manage CLI Tools Globally and Easily

From `black` to `ruff`, Get Your Tools Hassle-Free

Globally:

uv tool install ruff

Locally within a Project:

uv add ruff

Run Ephemeral Commands without Installing Globally:

uvx black my_code.py

Say goodbye to package conflicts and environment pollution — just run your tools whenever and wherever you need them.

🚀 Ready to Take `uv` for a Spin?

If you’re looking to supercharge your Python development and want to stop wrestling with multiple tools, uv is your answer.

With its streamlined commands, reproducible environments, and efficient package management, uv makes Python development a pleasure rather than a chore.

📌 Stay tuned for Part 2, where we’ll dive deeper into advanced features like leveraging pyproject.toml, handling global vs. local tool installations, and how uv can be your best friend when managing complex environments.

💡 For full details and documentation, check out uv documentation.

🐍✨ Happy coding!