Skip to content

uv

A Dagger module for uv-managed Python projects and workspaces.

API reference

This site is a tutorial. The exact functions, arguments, and types are published as generated reference documentation on the Daggerverse.

The module's main job is building selected packages from a uv workspace. A workspace package usually depends on sibling packages by path, and those have to be present and installed in the right order before the package itself can be installed.

The module reads your uv.lock, works out which local members the target needs, and stages them, so one call turns a monorepo package into a minimal container.

It can also:

  • Package a project as a relocatable virtual environment that runs in a fresh container with no Python of its own.
  • Audit the locked dependencies of every workspace in a source tree.

Each workspace knows its own uv version

Each workspace reads its required-version (from uv.toml, or the [tool.uv] table of pyproject.toml) and resolves it to a concrete image tag. The audit image and the default build base both use that version, so the tooling matches what the project declares. You can override the version or pass your own image.

Installation

Install it into your workspace, which makes its checks (one audit per uv workspace) available to dagger check:

$ dagger install github.com/typesafe-ai/daggerverse/uv

Or add it as a client of your own Dagger module:

$ dagger module client add github.com/typesafe-ai/daggerverse/uv

Quickstart

Build a minimal container with a package and its local dependencies installed:

$ dagger call uv workspace --path . install --package my-app

Audit every workspace in the source tree:

$ dagger check --uv

from dagger_clients.uv import uv

# Build a minimal container with a package and its local dependencies installed.
ctr = uv(ws).workspace(".").install(package=["my-app"])

ws is the Dagger workspace the module reads. In your own module, take ws: Workspace as an argument and Dagger fills it in. To read a directory instead, pass directory.as_workspace().

The mental model 
graph LR
  Uv["Uv<br/><i>(your source tree)</i>"] -->|workspace / workspaces| WS["UvWorkspaceSource<br/><i>(one per uv.lock)</i>"]
  WS -->|build| B["UvWorkspaceBuild<br/><i>(container + sync plan)</i>"]
  WS -->|install| C1["Container"]
  B -->|with_local_dependencies / copy_venv| C2["Container"]
  B -->|venv| V["UvVenv<br/><i>(venv + its Python)</i>"]
  • Uv holds the source tree it reads from the Dagger workspace (ws). Ask it for one workspace by path (workspace) or for the collection of every workspace it finds (workspaces).
  • UvWorkspaceSource is one uv workspace (the files rooted at a uv.lock). From it you can read the required uv version, audit it (a check), build a container step by step, or install everything in one call.
  • UvWorkspaceBuild is an in-progress build: a container plus the resolved sync plan. It exposes the individual pipeline steps so you can run your own steps between them, and exports the result as a container or a UvVenv.

The convenience methods (audit, install) cover the common cases. Use the pipeline when you need control over the individual steps.

Where to go next