community.general.uv_python module – Manage Python versions and installations using the uv Python package manager

Note

This module is part of the community.general collection (version 13.1.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.general.uv_python.

New in community.general 13.0.0

Synopsis

  • Install, uninstall or upgrade Python versions managed by uv.

Requirements

The below requirements are needed on the host that executes this module.

  • uv must be installed and available in PATH and must be at least 0.8.0.

Parameters

Parameter

Comments

state

string

Desired state of the specified Python version.

present ensures the specified version is installed. If you specify a full patch version (for example version=3.12.3), that exact version is be installed if not already present. If you only specify a minor version (for example 3.12), the latest available patch version for that minor release is installed only if no patch version for that minor release is currently installed (including patch versions not managed by uv). python_versions and python_paths lengths are always equal to one for this state.

absent ensures the specified version is removed. If you specify a full patch version, only that exact patch version is removed. If you only specify a minor version (for example 3.12), all installed patch versions for that minor release are removed. If you specify a version that is not installed, no changes are made. python_versions and python_paths lengths can be higher or equal to one in this state.

latest ensures the latest available patch version for the specified version is installed. If you only specify a minor version (for example 3.12), the latest available patch version for that minor release is always installed. If another patch version is already installed but is not the latest, the latest patch version is installed. The latest patch version installed depends on the uv version, since available Python versions are frozen per uv release. python_versions and python_paths lengths are always equal to one in this state. This state does not use uv python upgrade.

Choices:

  • "present" ← (default)

  • "absent"

  • "latest"

version

string / required

Python version to manage.

Not all canonical Python versions are supported in this release. Valid version numbers consist of two or three dot-separated numeric components, with an optional ‘pre-release’ tag at the end such as 3.12, 3.12.3, 3.15.0a5.

Advanced uv selectors such as >=3.12,<3.13 or cpython@3.12 are not supported in this release.

When you specify only a major.minor version, make sure the number is enclosed in quotes so that it gets parsed correctly. Note that in case only a major.minor version are specified behavior depends on the state parameter.

Attributes

Attribute

Support

Description

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: none

Returns details on what has changed (or possibly needs changing in check_mode), when in diff mode.

See Also

See also

C(uv) documentation

Python versions management with uv.

C(uv) CLI documentation

uv CLI reference guide.

Examples

- name: Install Python 3.14
  community.general.uv_python:
    version: "3.14"

- name: Upgrade Python 3.14
  community.general.uv_python:
    version: "3.14"
    state: latest

- name: Remove Python 3.13.5
  community.general.uv_python:
    version: 3.13.5
    state: absent

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

python_paths

list / elements=string

List of installation paths of Python versions changed.

Returned: success

Sample: ["/root/.local/share/uv/python/cpython-3.13.5-linux-x86_64-gnu/bin/python3.13"]

python_versions

list / elements=string

List of Python versions changed.

Returned: success

Sample: ["3.13.5"]

rc

integer

Return code of the executed command.

Returned: success

Sample: 0

stderr

string

Stderr of the executed command.

Returned: success

Sample: ""

stdout

string

Stdout of the executed command.

Returned: success

Sample: ""

Authors

  • Mariam Ahhttouche (@mriamah)