uv plugin¶
The uv plugin can be used for Python projects that use the uv build tool.
Keywords¶
In addition to the common plugin and sources keywords, this plugin provides the following plugin-specific keywords:
uv-extras¶
Type: list of strings
Extra dependencies to build with. Each element of the list is passed
exactly as --extra EXTRA.
uv-groups¶
Type: list of strings
Extra dependency groups to build with. Each element of the list is passed
exactly as --group GROUP.
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 value: 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 value: See below
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.
UV_PYTHON_DOWNLOADS¶
Default value: “never”
Whether or not to automatically download Python if the requested version is missing.
UV_PYTHON¶
Default value: ${PARTS_PYTHON_INTERPRETER}
The version of Python that uv should use. See Python plugin environment variables for more information.
UV_PYTHON_PREFERENCE¶
Default value: “only-system”
Possible values: only-system, only-managed, system, managed
Whether uv should prefer (or exclusively use) system or uv-managed Python versions.
Dependencies¶
Since none of the bases that are available for rocks contain a default Python
installation, including a Python interpreter in Rockcraft projects is mandatory.
Both the python and the poetry plugins also require the venv module
to create the virtual environment where Python packages are installed at build
time.
The easiest way to do this is to include the python3-venv package in the
stage-packages of the part that uses the Python-based plugin. This will pull
in the default Python interpreter for the build-base, like Python 3.10 for
Ubuntu 22.04. However, other versions can be used by explicitly declaring them -
here’s an example that uses python3.12-venv from the Deadsnakes ppa:
package-repositories:
- type: apt
ppa: deadsnakes/ppa
priority: always
parts:
my-part:
plugin: <python or poetry>
source: .
stage-packages: [python3.12-venv]
How it works¶
During the build step, the plugin performs the following actions:
It creates a virtual environment in the
${CRAFT_PART_INSTALL}directory.It uses uv sync to install the required Python packages from the provided
uv.lockfile.