pip – Manages Python library dependencies
Synopsis
- Manage Python library dependencies. To use this module, one of the following keys is required:
name
orrequirements
.
Requirements
The below requirements are needed on the host that executes this module.
- pip
- virtualenv
- setuptools
Parameters
Parameter | Choices/Defaults | Comments |
---|---|---|
chdir
path
|
cd into this directory before running the command
|
|
editable
boolean
|
|
Pass the editable flag.
|
executable
path
|
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
|
Extra arguments passed to pip.
|
|
name
list
|
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
|
|
The state of module
The 'forcereinstall' option is only available in Ansible 2.1 and above.
|
umask
string
|
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
|
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
|
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
|
|
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
# 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 python package using a proxy - it 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' # 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 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" # Install (Bottle) for Python 3.3 specifically,using the 'pip3.3' executable. - pip: name: bottle executable: pip3.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 not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Core Team. [core]
Red Hat Support
More information about Red Hat’s support of this module is available from this Red Hat Knowledge Base article.
Authors
- Matt Wright (@mattupstate)
Hint
If you notice any issues in this documentation, you can edit this document to improve it.
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.9/modules/pip_module.html