Uv Operations

Operations for uv:

  • install, remove or upgrade Python packages

  • install, remove or upgrade ‘tools’

  • create or remove virtual environments (venv’s)

  • ensure the uv tool executable directory is on the PATH

Facts used in these operations: files.File, uv.UvInstalledPythonsByVersion, uv.UvPipPackages, uv.UvToolDir, uv.UvTools.

uv.packages

Install/remove/update Python packages using uv pip

uv.packages(
     packages: 'str | list[str]',
     *,
     requirements: 'str | None' = None,
     present: 'bool' = True,
     latest: 'bool' = False,
     extra_args: 'str | list[str] | None' = None,
     **kwargs,
)

  • packages: a package or list of packages to install/uninstall

  • requirements: optionally a path to a requirements file to install/uninstall. Default None.

  • present: whether the packages should be installed or uninstalled. Default True.

  • latest: whether to upgrade packages for which a version was not specified. Default False.

  • extra_args: zero or more additional arguments to the uv command. Default None.

Python Package versions:

Package versions can be specified in the usual manner, e.g. <pkg>==<version>.

Example:

uv.packages(
    name="Install Requests",
    packages=["requests"],
)

Note

This operation also inherits all global arguments.

uv.pythons

Install/remove Python version(s).

uv.pythons(
     versions: 'str | list[str]',
     *,
     present: 'bool' = True,
     managed: 'bool' = True,
     extra_args: 'str | list[str] | None' = None,
     **kwargs,
)

  • version: a version or list of Python versions

  • present: whether the versions should be installed or removed. Default True.

  • managed: whether only managed or all available version should be considered. Default True.

  • extra_args: zero or more additional arguments to be passed to uv. Default None.

Example:

uv.pythons(
    name="Install Python 3.13 and 3.14",
    versions=["3.14", "3.13"],
    present=True
)

Note

This operation also inherits all global arguments.

uv.tools

Install/remove/update packages using uv tool.

uv.tools(
     tools: 'str | list[str]',
     *,
     present: 'bool' = True,
     latest: 'bool' = False,
     extra_args: 'str | list[str] | None' = None,
     **kwargs,
)

  • tools: a package or list of packages to install as tools

  • present: whether the packages should be installed or uninstalled. Default True.

  • latest: whether or not to upgrade packages without a specified version. Default False.

  • extra_args: zero or more additional arguments to uv. Default None.

Versions:

Tool versions may be, but are not required to be, specified in the usual manner: <pkg>==<version>.

Example:

uv.tools(
    name="Install Pyinfra",
    tools=["pyinfra"],
    present=True
)

Note

This operation also inherits all global arguments.

uv.tools_update_shell

Ensure that the uv tool executable directory is on the PATH.

uv.tools_update_shell**kwargs,    )

Note

This operation also inherits all global arguments.

uv.tools_upgrade_all

Upgrade all uv tools.

uv.tools_upgrade_all(*, extra_args: 'str | list[str] | None' = None,
     **kwargs,
)

  • extra_args: zero or more additional arguments to uv. Default None.

Note

This operation also inherits all global arguments.

uv.venv

Add/remove a Python venv in the specified location.

uv.venv(
     path: 'str',
     *,
     present: 'bool' = True,
     python: 'str | None' = None,
     allow_existing: 'bool' = False,
     clear_existing: 'bool' = False,
     link_mode: "Literal['clone', 'copy', 'hardlink', 'symlink'] | None" = None,
     seed: 'bool' = False,
     site_packages: 'bool' = False,
     extra_args: 'str | list[str] | None' = None,
     **kwargs,
)

  • path: where to create the venv

  • present: whether the venv should be created or removed. Default True

  • python: Python interpreter to use. Defaults to not specified.

  • allow_existing: allow (and retain) existing files in the venv directory. Default False

  • clear_existing: remove all existing files in the venv directory. Default False

  • seed: whether to seed the venv with pip, and pre-3.12, setuptools and wheel. Default False

  • site_packages: give the venv access to the global site-packages. Default False

  • link_mode: method to use when installing seed packages: clone, copy, hardlink or symlink. Default is platform-dependent

  • extra_args: zero or more additional arguments to the ‘uv’ command

Example:

uv.venv(
    name="Create a venv",
    path="/my/projects/useful-project/.venv",
)

Note

This operation also inherits all global arguments.