pip - Manages Python library dependencies¶

Synopsis
- Requirements
Parameters
Notes
Examples
Return Values
Status
Maintenance
- Support
- Author

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 (added in 1.3)		cd into this directory before running the command
editable bool (added in 2.0)	Choices: no ← yes	Pass the editable flag.
executable (added in 1.3)		The explicit executable or a pathname to the executable to be used to run pip for a specific version of Python installed in the system. For example `pip-3.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. It cannot be specified together with the 'virtualenv' parameter (added in 2.1). By default, it will take the appropriate version for the python interpreter use by ansible, e.g. pip3 on python 3, and pip2 or pip on python 2.
extra_args		Extra arguments passed to pip.
name		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		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	Choices: absent forcereinstall latest present ←	The state of module The 'forcereinstall' option is only available in Ansible 2.1 and above.
umask (added in 2.1)		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		The version number to install of the Python library specified in the name parameter.
virtualenv		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	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 (added in 2.0)		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 bool	Choices: 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

Please note that 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.
By default, this module will use the appropriate version of pip for the interpreter used by ansible (e.g. pip3 when using python 3, pip2 otherwise)

Examples ¶

# Install (Bottle) python package.
- pip:
    name: bottle

# Install (Bottle) python package on version 0.11.
- pip:
    name: bottle==0.11

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

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

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

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

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

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

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

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

# Install (Bottle) within a user home directory.
- pip:
    name: bottle
    extra_args: --user

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

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

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

# Install (Bottle) for Python 3.3 specifically,using the 'pip-3.3' executable.
- pip:
    name: bottle
    executable: pip-3.3

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

# 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	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

Status ¶

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

Maintenance ¶

This module is flagged as core which means that it is maintained by the Ansible Core Team. See Module Maintenance & Support for more info.

For a list of other modules that are also maintained by the Ansible Core Team, see here.

Support ¶

For more information about Red Hat’s support of this module, please refer to this Knowledge Base article

Author ¶

Matt Wright (@mattupstate)

Hint

If you notice any issues in this documentation you can edit this document to improve it.