uv plugin¶

The uv plugin can be used for Python projects that use the uv build tool.

Keys¶

This plugin provides the following unique keys.

uv-extras¶

Type

set[str]

Description

The extra dependencies to include in the part.

uv-groups¶

Type

set[str]

Description

The extra dependency groups to build with.

Environment variables¶

Along with the variables defined by the Python plugin, this plugin responds to its own special variables.

Note

This section describes how this plugin uses uv-specific environment variables. For more information, as well as a complete list of environment variables for uv, see the uv environment documentation.

UV_FROZEN¶

Default: true

Whether or not to update the uv.lock file. If true, uv.lock must exist and will be used as the single source of truth for dependency versions, with no attempt made to update them before installation.

UV_PROJECT_ENVIRONMENT¶

Default: ${CRAFT_PART_INSTALL}

A path to the Python virtual environment to build with. By default, this variable populates itself with the directory in which this plugin will create the virtual environment.

Because the default virtual environment is created in ${CRAFT_PART_INSTALL}, avoid unpacking unrelated stage-packages into the same part. If those packages must be staged, define them in a separate part and list that part in the uv part’s after key.

UV_PYTHON_DOWNLOADS¶

Default: “never”

Whether or not to automatically download Python if the requested version is missing.

UV_PYTHON¶

Default: ${PARTS_PYTHON_INTERPRETER}

The version of Python that uv should use.

UV_PYTHON_PREFERENCE¶

Choices: “only-system”, “only-managed”, “system”, or “managed”

Default: “only-system”

Whether uv should prefer (or exclusively use) system or uv-managed Python versions.

UV_COMPILE_BYTECODE¶

Default: true

Whether uv should compile Python sources to bytecode when creating the virtual environment.

Dependencies¶

The uv plugin needs the uv executable but does not provision it by itself, to allow flexibility in the choice of version.

One way of providing uv is the astral-uv snap, declared as a build-snap from the desired channel.

An alternative method is to define a part with the name uv-deps, and declare that the part using the uv plugin comes after the uv-deps part with the after key. In this case, the plugin will assume that this new part will stage the uv executable to be used in the build step. For installation instructions, see uv documentation.

How it works¶

During the build step, the plugin performs the following actions:

Create a virtual environment in the ${CRAFT_PART_INSTALL} directory.
Use uv sync to install the required Python packages from the provided uv.lock file.