ansible.builtin.pip – Manages Python library dependencies

Note

This module is part of ansible-base and included in all Ansible installations. In most cases, you can use the short module name pip even without specifying the collections: keyword. Despite that, we recommend you use the FQCN for easy linking to the module documentation and to avoid conflicting with other collections that may have the same module name.

New in version 0.7: of ansible.builtin

Synopsis
Requirements
Parameters
Notes
Examples
Return Values

Synopsis

Manage Python library dependencies. To use this module, one of the following keys is required: name or requirements.

Requirements

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

pip
virtualenv
setuptools

Parameters

Parameter	Choices/Defaults	Comments
chdir path added in 1.3 of ansible.builtin		cd into this directory before running the command
editable boolean added in 2.0 of ansible.builtin	no ← yes	Pass the editable flag.
executable path added in 1.3 of ansible.builtin		The explicit executable or pathname for the pip executable, if different from the Ansible Python interpreter. For example `pip3.3`, if there are both Python 2.7 and 3.3 installations in the system and you want to run pip for the Python 3.3 installation. Mutually exclusive with virtualenv (added in 2.1). Does not affect the Ansible Python interpreter. The setuptools package must be installed for both the Ansible Python interpreter and for the version of Python specified by this option.
extra_args string added in 1.0 of ansible.builtin		Extra arguments passed to pip.
name list / elements=string		The name of a Python library to install or the url(bzr+,hg+,git+,svn+) of the remote package. This can be a list (since 2.2) and contain version specifiers (since 2.7).
requirements string		The path to a pip requirements file, which should be local to the remote system. File can be specified as a relative path if using the chdir option.
state string	absent forcereinstall latest present ←	The state of module The 'forcereinstall' option is only available in Ansible 2.1 and above.
umask string added in 2.1 of ansible.builtin		The system umask to apply before installing the pip package. This is useful, for example, when installing on systems that have a very restrictive umask by default (e.g., "0077") and you want to pip install packages which are to be used by all users. Note that this requires you to specify desired umask mode as an octal string, (e.g., "0022").
version string		The version number to install of the Python library specified in the name parameter.
virtualenv path		An optional path to a virtualenv directory to install into. It cannot be specified together with the 'executable' parameter (added in 2.1). If the virtualenv does not exist, it will be created before installing packages. The optional virtualenv_site_packages, virtualenv_command, and virtualenv_python options affect the creation of the virtualenv.
virtualenv_command path added in 1.1 of ansible.builtin	Default: "virtualenv"	The command or a pathname to the command to create the virtual environment with. For example `pyvenv`, `virtualenv`, `virtualenv2`, `~/bin/virtualenv`, `/usr/local/bin/virtualenv`.
virtualenv_python string added in 2.0 of ansible.builtin		The Python executable used for creating the virtual environment. For example `python3.5`, `python2.7`. When not specified, the Python version used to run the ansible module is used. This parameter should not be used when `virtualenv_command` is using `pyvenv` or the `-m venv` module.
virtualenv_site_packages boolean added in 1.0 of ansible.builtin	no ← yes	Whether the virtual environment will inherit packages from the global site-packages directory. Note that if this setting is changed on an already existing virtual environment it will not have any effect, the environment must be deleted and newly created.

Notes

Note

The virtualenv (http://www.virtualenv.org/) must be installed on the remote host if the virtualenv parameter is specified and the virtualenv needs to be created.
Although it executes using the Ansible Python interpreter, the pip module shells out to run the actual pip command, so it can use any pip version you specify with executable. By default, it uses the pip version for the Ansible Python interpreter. For example, pip3 on python 3, and pip2 or pip on python 2.
The interpreter used by Ansible (see ansible_python_interpreter) requires the setuptools package, regardless of the version of pip set with the executable option.

Examples

- name: Install bottle python package
  pip:
    name: bottle

- name: Install bottle python package on version 0.11
  pip:
    name: bottle==0.11

- name: Install bottle python package with version specifiers
  pip:
    name: bottle>0.10,<0.20,!=0.11

- name: Install multi python packages with version specifiers
  pip:
    name:
      - django>1.11.0,<1.12.0
      - bottle>0.10,<0.20,!=0.11

- name: Install python package using a proxy
  # Pip doesn't use the standard environment variables, please use the CAPITALIZED ones below
  pip:
    name: six
  environment:
    HTTP_PROXY: '127.0.0.1:8080'
    HTTPS_PROXY: '127.0.0.1:8080'

# You do not have to supply '-e' option in extra_args
- name: Install MyApp using one of the remote protocols (bzr+,hg+,git+,svn+)
  pip:
    name: svn+http://myrepo/svn/MyApp#egg=MyApp

- name: Install MyApp using one of the remote protocols (bzr+,hg+,git+)
  pip:
    name: git+http://myrepo/app/MyApp

- name: Install MyApp from local tarball
  pip:
    name: file:///path/to/MyApp.tar.gz

- name: Install bottle into the specified (virtualenv), inheriting none of the globally installed modules
  pip:
    name: bottle
    virtualenv: /my_app/venv

- name: Install bottle into the specified (virtualenv), inheriting globally installed modules
  pip:
    name: bottle
    virtualenv: /my_app/venv
    virtualenv_site_packages: yes

- name: Install bottle into the specified (virtualenv), using Python 2.7
  pip:
    name: bottle
    virtualenv: /my_app/venv
    virtualenv_command: virtualenv-2.7

- name: Install bottle within a user home directory
  pip:
    name: bottle
    extra_args: --user

- name: Install specified python requirements
  pip:
    requirements: /my_app/requirements.txt

- name: Install specified python requirements in indicated (virtualenv)
  pip:
    requirements: /my_app/requirements.txt
    virtualenv: /my_app/venv

- name: Install specified python requirements and custom Index URL
  pip:
    requirements: /my_app/requirements.txt
    extra_args: -i https://example.com/pypi/simple

- name: Install specified python requirements offline from a local directory with downloaded packages
  pip:
    requirements: /my_app/requirements.txt
    extra_args: "--no-index --find-links=file:///my_downloaded_packages_dir"

- name: Install bottle for Python 3.3 specifically, using the 'pip3.3' executable
  pip:
    name: bottle
    executable: pip3.3

- name: Install bottle, forcing reinstallation if it's already installed
  pip:
    name: bottle
    state: forcereinstall

- name: Install bottle while ensuring the umask is 0022 (to ensure other users can use it)
  pip:
    name: bottle
    umask: "0022"
  become: True

Return Values

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

Key	Returned	Description
cmd string	success	pip command used by the module Sample: pip2 install ansible six
name list / elements=string	success	list of python modules targetted by pip Sample: ['ansible', 'six']
requirements string	success, if a requirements file was provided	Path to the requirements file Sample: /srv/git/project/requirements.txt
version string	success, if a name and version were provided	Version of the package specified in 'name' Sample: 2.5.1
virtualenv string	success, if a virtualenv path was provided	Path to the virtualenv Sample: /tmp/virtualenv

Authors

Matt Wright (@mattupstate)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.11/collections/ansible/builtin/pip_module.html