uv_project_dependencies
uv_project_dependencies installs what a Python application's uv.lock
lists into the application's virtual environment, .venv, with
uv sync --locked, as the application's account. The task names the
directory on the node that holds pyproject.toml and the lock file, usually
a release directory or a checkout. An application that lists its packages in
a requirements.txt is pip_package's, with
requirements_file_on_node and a virtual environment.
The five lock file modules work the same way: the lock file is never
rewritten, and a record in the lock file directory makes a rerun unchanged.
That is in
install what an application's lock file lists
and in the design's
what the lock file modules share.
The shared rules for MMX modules that install language packages and tools,
including the inputs
run_as_user_account, uv_program_path, and env, are in
what the installers share.
Set up
uv is one program. Its release archive for each processor architecture holds it; unpack the archive of a pinned release:
- when: {equals: ["{{ .node.arch }}", amd64]}
unpack_archive:
url: https://github.com/astral-sh/uv/releases/download/0.13.0/uv-x86_64-unknown-linux-gnu.tar.gz
sha256: 1468ebd5a5541121837c5a2817b9972ba6090fa6caa3d142620850a47fb75154
path: /opt/uv-0.13.0
unpack_without_wrapping_folder: true
- when: {equals: ["{{ .node.arch }}", arm64]}
unpack_archive:
url: https://github.com/astral-sh/uv/releases/download/0.13.0/uv-aarch64-unknown-linux-gnu.tar.gz
sha256: 3ccfb6af6e242433eb552f7d9676abd5412c6595c497e990d9c8cb7b5bd4d2c3
path: /opt/uv-0.13.0
unpack_without_wrapping_folder: true
The node gets /opt/uv-0.13.0/uv. uv also needs a Python that the project
accepts: the distribution's python3, or one that uv installs, as the
recipe for version managers
shows.
Inputs
lock_file_dir(string; required): the directory on the node that holds pyproject.toml and uv.lock, usually a release directory or a checkout; the virtual environment is its .venvrun_as_user_account(string; required): the application's account, which runs uv: uv runs code from the packages it buildsinclude_development_dependencies(boolean; required): false passes --no-group dev; true passes --group dev; other groups follow the application's uv settingsuv_program_path(string; default found on the standard path): a written value must be absolute; the uv program to run when it is not uv on the standard path, such as uv unpacked under /optpython_program_path(string; optional): absolute path to the Python executable for the virtual environment, such as a Python installed under /opt with uv python install. When python_program_path is omitted, uv chooses an installed Python version accepted by the projectenv(mapping; optional): environment variables for uv, such as UV_INDEX_URL or a token for a private package index; values may be secrets
Outputs
The node task's result holds these fields. A later node task reads them as .node_tasks.<id>.<field>, where <id> is the node task's id.
statuschangevalue
What a dryrun reports
Compares the record and reports unchanged or would change with the reason; a lock file directory that does not exist yet, a lock file that an earlier node task would change, or a python_program_path that is not installed yet, is not checked.
Retries and time limits
Bounded automatic retries by default; retry: false turns them off.
The node task takes the time limits time_limit and time_limit_per_try; without them, the project's node_task_defaults apply. mmx describe-module task describes the settings every node task accepts.
Examples
Install a release's packages without development dependencies
- uv_project_dependencies:
lock_file_dir: /srv/myapp/releases/v1.4.2
run_as_user_account: myapp
include_development_dependencies: false
uv_program_path: /opt/uv-0.13.0/uv
include_development_dependencies is required: false leaves out the
dev group with --no-group dev, and true installs the dev group with
--group dev. Other groups follow the application's uv settings.
On the node, MMX runs
uv sync --locked --no-python-downloads --no-group dev in
/srv/myapp/releases/v1.4.2 as the account myapp. uv creates .venv in
that directory with a Python it finds on the node, installs exactly what
uv.lock lists, and removes from .venv what the lock file does not list.
After a successful installation, MMX writes the record
.mmx-uv-project-dependencies in the same directory; the next run is
unchanged while the record matches and .venv exists.
Use a Python that uv installed
- uv_project_dependencies:
lock_file_dir: /srv/myapp/releases/v1.4.2
run_as_user_account: myapp
include_development_dependencies: false
uv_program_path: /opt/uv-0.13.0/uv
python_program_path: /opt/uv-python/cpython-3.14.8-linux-x86_64-gnu/bin/python3
MMX passes the Python to uv with --python, and the record holds its
version, so a new Python installs the packages again. An earlier shell
task installs that Python, as the
recipe for version managers
shows. A systemd unit then starts the application from
/srv/myapp/releases/v1.4.2/.venv/bin/.
How it works
uv sync --locked reads uv.lock and fails when the lock file is missing
or no longer fits pyproject.toml; it never writes the lock file. MMX runs
uv only when the installation record does not match, as for every lock file
module. A changed pyproject.toml in lock_file_dir makes MMX run uv again
even when uv.lock did not change, so uv checks whether the lock file still
fits. Without python_program_path, uv chooses an installed Python that
the project's requires-python and .python-version accept.
Without python_program_path, the record holds the version of python3
on the installer's PATH.
uv keeps downloaded packages in a cache in the home directory of the account
named in run_as_user_account.
Errors and what they mean
uv.lockis missing: the task fails and names the lock file. Commituv.lockwith the application.- The lock file no longer fits
pyproject.toml: uv's own message says that the lock file needs to be updated. Runuv lockwhere the application is developed, and commit the newuv.lock. - No Python that the project accepts: uv's message says that no
interpreter fits the project's
requires-python. Install a fitting Python in an earlier task, and name the installed Python executable inpython_program_path.
Tested on
Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10.
The suite language_installers.py runs on Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, and AlmaLinux 10, with
uv 0.13.0 from its release archive, and installs against a lock file that the
suite makes on the node, as a repository would carry it: first with the
distribution's python3 (3.9 on Rocky Linux 9), then with Python 3.14.8
from uv python install, named in python_program_path.
Why it works this way
-
uv never downloads a Python here. uv would otherwise fetch one into the account's home directory when none fits, an installation that no node task shows and a dryrun cannot preview. Installing Python is a task of its own.
-
--locked, not--frozen. Both install whatuv.locklists, but--frozenalso installs from a lock file that no longer fitspyproject.toml;--lockedfails, asnpm cidoes. -
The development group is explicit. Passing
--group devor--no-group devmakes the task's choice apply even when uv's configured default groups leavedevout. -
A changed manifest reaches the installer's lock-file check. The shared installation record prevents an old successful installation from hiding a manifest change.
-
A written program path is absolute. Leaving the path out uses the installer's normal program selection, as the shared inputs explain.
This page is docs/reference/modules/uv_project_dependencies.md in the MMX repository.