W3cubDocs

/Ansible

community.general.pipx module – Manages applications installed with pipx

Note

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

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.pipx.

New in community.general 3.8.0

Synopsis
Requirements
Parameters
Attributes
Notes
See Also
Examples
Return Values

Synopsis

Manage Python applications installed in isolated virtualenvs using pipx.

Requirements

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

When using name with version specifiers, the Python package packaging is required.
If the package packaging is at a version lesser than 22.0.0, it fails silently when processing invalid specifiers, like tox<<<<4.0.

Parameters

Parameter	Comments
editable boolean added in community.general 4.6.0	Install the project in editable mode. Choices: `false` ← (default) `true`
executable path	Path to the `pipx` installed in the system. If not specified, the module will use `python -m pipx` to run the tool, using the same Python interpreter as ansible itself.
force boolean	Force modification of the application’s virtual environment. See `pipx` for details. Only used when `state=install`, `state=upgrade`, `state=upgrade_all`, `state=latest`, or `state=inject`. The module is not idempotent when `force=true`. Choices: `false` ← (default) `true`
global boolean added in community.general 9.4.0	The module will pass the `--global` argument to `pipx`, to execute actions in global scope. The `--global` is only available in `pipx>=1.6.0`, so make sure to have a compatible version when using this option. Moreover, a nasty bug with `--global` was fixed in `pipx==1.7.0`, so it is strongly recommended you used that version or newer. Choices: `false` ← (default) `true`
include_injected boolean	Upgrade the injected packages along with the application. Only used when `state=upgrade`, `state=upgrade_all`, or `state=latest`. This is used with `state=upgrade` and `state=latest` since community.general 6.6.0. Choices: `false` ← (default) `true`
index_url string	Base URL of Python Package Index. Only used when `state=install`, `state=upgrade`, `state=latest`, or `state=inject`.
inject_packages list / elements=string	Packages to be injected into an existing virtual environment. Only used when `state=inject`.
install_apps boolean added in community.general 6.5.0	Add apps from the injected packages. Only used when `state=inject`. Choices: `false` ← (default) `true`
install_deps boolean	Include applications of dependent packages. Only used when `state=install`, `state=latest`, or `state=inject`. Choices: `false` ← (default) `true`
name string	The name of the application and also the name of the Python package being installed. In `pipx` documentation it is also referred to as the name of the virtual environment where the application is installed. If `name` is a simple package name without version specifiers, then that name is used as the Python package name to be installed. Starting in community.general 10.7.0, you can use package specifiers when `state=present` or `state=install`. For example, `name=tox<4.0.0` or `name=tox>3.0.27`. Please note that when you use `state=present` and `name` with version specifiers, contrary to the behavior of `pipx`, this module honors the version specifier and installs a version of the application that satisfies it. If you want to ensure the reinstallation of the application even when the version specifier is met, then you must use `force=true`, or perhaps use `state=upgrade` instead. Use `source` for installing from URLs or directories.
pip_args string added in community.general 4.6.0	Arbitrary arguments to pass directly to `pip`.
python string	Python version to be used when creating the application virtual environment. Must be 3.6+. Only used when `state=install`, `state=latest`, `state=reinstall`, or `state=reinstall_all`.
source string	Source for the package. This option is used when `state=install` or `state=latest`, and it is ignored with other states. Use `source` when installing a Python package with version specifier, or from a local path, from a VCS URL or compressed file. The value of this option is passed as-is to `pipx`. `name` is still required when using `source` to establish the application name without fetching the package from a remote source. The module is not idempotent when using `source`.
spec_metadata path added in community.general 9.4.0	Spec metadata file for `state=install_all`. This content of the file is usually generated with `pipx list --json`, and it can be obtained with community.general.pipx_info with `include_raw=true` and obtaining the content from the `raw_output`.
state string	Desired state for the application. The states `present` and `absent` are aliases to `install` and `uninstall`, respectively. The state `latest` is equivalent to executing the task twice, with state `install` and then `upgrade`. It was added in community.general 5.5.0. The states `install_all`, `uninject`, `upgrade_shared`, `pin` and `unpin` are only available in `pipx>=1.6.0`, make sure to have a compatible version when using this option. These states have been added in community.general 9.4.0. Choices: `"present"` `"absent"` `"install"` ← (default) `"install_all"` `"uninstall"` `"uninstall_all"` `"inject"` `"uninject"` `"upgrade"` `"upgrade_shared"` `"upgrade_all"` `"reinstall"` `"reinstall_all"` `"latest"` `"pin"` `"unpin"`
suffix string added in community.general 9.3.0	Optional suffix for virtual environment and executable names. Warning: `pipx` documentation states this is an experimental feature subject to change.
system_site_packages boolean added in community.general 6.6.0	Give application virtual environment access to the system site-packages directory. Only used when `state=install` or `state=latest`. Choices: `false` ← (default) `true`

Attributes

Attribute	Support	Description
check_mode	Support: full	Can run in `check_mode` and return changed status prediction without modifying target.
diff_mode	Support: full	Will return details on what has changed (or possibly needs changing in `check_mode`), when in diff mode.

Notes

Note

This module requires pipx version 0.16.2.1 or above. From community.general 11.0.0 onwards, the module will require pipx>=1.7.0.
Please note that pipx requires Python 3.6 or above.
This module does not install the pipx python package, however that can be easily done with the module ansible.builtin.pip.
This module does not require pipx to be in the shell PATH, but it must be loadable by Python as a module.
This module will honor pipx environment variables such as but not limited to PIPX_HOME and PIPX_BIN_DIR passed using the environment Ansible keyword.

Examples

- name: Install tox
  community.general.pipx:
    name: tox

- name: Install tox from git repository
  community.general.pipx:
    name: tox
    source: git+https://github.com/tox-dev/tox.git

- name: Upgrade tox
  community.general.pipx:
    name: tox
    state: upgrade

- name: Install or upgrade tox with extra 'docs'
  community.general.pipx:
    name: tox
    source: tox[docs]
    state: latest

- name: Reinstall black with specific Python version
  community.general.pipx:
    name: black
    state: reinstall
    python: 3.7

- name: Uninstall pycowsay
  community.general.pipx:
    name: pycowsay
    state: absent

- name: Install multiple packages from list
  vars:
    pipx_packages:
      - pycowsay
      - black
      - tox
  community.general.pipx:
    name: "{{ item }}"
    state: latest
  with_items: "{{ pipx_packages }}"

Return Values

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

Key	Description
version string added in community.general 10.1.0	Version of pipx. Returned: always Sample: `"1.7.1"`

Authors

Alexei Znamensky (@russoz)

Collection links

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/general/pipx_module.html