salt.modules.pip
Install Python packages with pip to either the system or a virtualenv
Windows Support
New in version 2014.7.4.
Salt now uses a portable python. As a result the entire pip module is now functional on the salt installation itself. You can pip install dependencies for your custom modules. You can even upgrade salt itself using pip. For this to work properly, you must specify the Current Working Directory (cwd
) and the Pip Binary (bin_env
) salt should use. The variable pip_bin
can be either a virtualenv path or the path to the pip binary itself.
For example, the following command will list all software installed using pip to your current salt environment:
salt <minion> pip.list cwd='C:\salt\bin\Scripts' bin_env='C:\salt\bin\Scripts\pip.exe'
Specifying the cwd
and bin_env
options ensures you're modifying the salt environment. If these are omitted, it will default to the local installation of python. If python is not installed locally it will fail saying it couldn't find pip.
State File Support
This functionality works in states as well. If you need to pip install colorama with a state, for example, the following will work:
install_colorama: pip.installed: - name: colorama - cwd: 'C:\salt\bin\scripts' - bin_env: 'C:\salt\bin\scripts\pip.exe' - upgrade: True
Upgrading Salt using Pip
You can now update salt using pip to any version from the 2014.7 branch forward. Previous version require recompiling some of the dependencies which is painful in windows.
To do this you just use pip with git to update to the version you want and then restart the service. Here is a sample state file that upgrades salt to the head of the 2015.5 branch:
install_salt: pip.installed: - cwd: 'C:\salt\bin\scripts' - bin_env: 'C:\salt\bin\scripts\pip.exe' - editable: git+https://github.com/saltstack/[email protected]#egg=salt - upgrade: True restart_service: service.running: - name: salt-minion - enable: True - watch: - pip: install_salt
Note
If you're having problems, you might try doubling the back slashes. For example, cwd: 'C:\salt\bin\scripts'. Sometimes python thinks the single back slash is an escape character.
There is a known incompatibility between Python2 pip>=10.* and Salt <=2018.3.0. The issue is described here: https://github.com/saltstack/salt/issues/46163
-
Return a list of installed packages either globally or in the specified virtualenv
- bin_env
-
Path to pip (or to a virtualenv). This can be used to specify the path to the pip to use when more than one Python release is installed (e.g.
/usr/bin/pip-2.7
or/usr/bin/pip-2.6
. If a directory path is specified, it is assumed to be a virtualenv. - user
-
The user under which to run pip
- cwd
-
Directory from which to run pip
Note
If the version of pip available is older than 8.0.3, the list will not include the packages
pip
,wheel
,setuptools
, ordistribute
even if they are installed.CLI Example:
salt '*' pip.freeze bin_env=/home/code/path/to/virtualenv
salt.modules.pip.freeze(bin_env=None, user=None, cwd=None, use_vt=False, env_vars=None, **kwargs)
-
Install packages with pip
Install packages individually or from a pip requirements file. Install packages globally or to a virtualenv.
- pkgs
-
Comma separated list of packages to install
- requirements
-
Path to requirements
- bin_env
-
Path to pip (or to a virtualenv). This can be used to specify the path to the pip to use when more than one Python release is installed (e.g.
/usr/bin/pip-2.7
or/usr/bin/pip-2.6
. If a directory path is specified, it is assumed to be a virtualenv.Note
For Windows, if the pip module is being used to upgrade the pip package, bin_env should be the path to the virtualenv or to the python binary that should be used. The pip command is unable to upgrade itself in Windows.
- use_wheel
-
Prefer wheel archives (requires pip>=1.4)
- no_use_wheel
-
Force to not use wheel archives (requires pip>=1.4,<10.0.0)
- no_binary
-
Force to not use binary packages (requires pip >= 7.0.0) Accepts either :all: to disable all binary packages, :none: to empty the set, or one or more package names with commas between them
- log
-
Log file where a complete (maximum verbosity) record will be kept
- proxy
-
Specify a proxy in the form
user:[email protected]:port
. Note that theuser:password@
is optional and required only if you are behind an authenticated proxy. If you provide[email protected]:port
then you will be prompted for a password.Note
If the Minion has a globaly configured proxy - it will be used even if no proxy was set here. To explicitly disable proxy for pip you should pass
False
as a value. - timeout
-
Set the socket timeout (default 15 seconds)
- editable
-
install something editable (e.g.
git+https://github.com/worldcompany/djangoembed.git#egg=djangoembed
) - find_links
-
URL to search for packages
- index_url
-
Base URL of Python Package Index
- extra_index_url
-
Extra URLs of package indexes to use in addition to
index_url
- no_index
-
Ignore package index
- mirrors
-
Specific mirror URL(s) to query (automatically adds --use-mirrors)
Warning
This option has been deprecated and removed in pip version 7.0.0. Please use
index_url
and/orextra_index_url
instead. - build
-
Unpack packages into
build
dir - target
-
Install packages into
target
dir - download
-
Download packages into
download
instead of installing them - download_cache | cache_dir
-
Cache downloaded packages in
download_cache
orcache_dir
dir - source
-
Check out
editable
packages intosource
dir - upgrade
-
Upgrade all packages to the newest available version
- force_reinstall
-
When upgrading, reinstall all packages even if they are already up-to-date.
- ignore_installed
-
Ignore the installed packages (reinstalling instead)
- exists_action
-
Default action when a path already exists: (s)witch, (i)gnore, (w)ipe, (b)ackup
- no_deps
-
Ignore package dependencies
- no_install
-
Download and unpack all packages, but don't actually install them
- no_download
-
Don't download any packages, just install the ones already downloaded (completes an install run with
--no-install
) - install_options
-
Extra arguments to be supplied to the setup.py install command (e.g. like
--install-option='--install-scripts=/usr/local/bin'
). Use multiple --install-option options to pass multiple options to setup.py install. If you are using an option with a directory path, be sure to use absolute path. - global_options
-
Extra global options to be supplied to the setup.py call before the install command.
- user
-
The user under which to run pip
- cwd
-
Directory from which to run pip
- pre_releases
-
Include pre-releases in the available versions
- cert
-
Provide a path to an alternate CA bundle
- allow_all_external
-
Allow the installation of all externally hosted files
- allow_external
-
Allow the installation of externally hosted files (comma separated list)
- allow_unverified
-
Allow the installation of insecure and unverifiable files (comma separated list)
- process_dependency_links
-
Enable the processing of dependency links
- env_vars
-
Set environment variables that some builds will depend on. For example, a Python C-module may have a Makefile that needs INCLUDE_PATH set to pick up a header file while compiling. This must be in the form of a dictionary or a mapping.
Example:
salt '*' pip.install django_app env_vars="{'CUSTOM_PATH': '/opt/django_app'}"
- trusted_host
-
Mark this host as trusted, even though it does not have valid or any HTTPS.
- use_vt
-
Use VT terminal emulation (see output while installing)
- no_cache_dir
-
Disable the cache.
- extra_args
-
pip keyword and positional arguments not yet implemented in salt
salt '*' pip.install pandas extra_args="[{'--latest-pip-kwarg':'param'}, '--latest-pip-arg']"
Warning
If unsupported options are passed here that are not supported in a minion's version of pip, a No such option error will be thrown.
Will be translated into the following pip command:
pip install pandas --latest-pip-kwarg param --latest-pip-arg
- disable_version_check
-
Pip may periodically check PyPI to determine whether a new version of pip is available to download. Passing True for this option disables that check.
CLI Example:
salt '*' pip.install <package name>,<package2 name> salt '*' pip.install requirements=/path/to/requirements.txt salt '*' pip.install <package name> bin_env=/path/to/virtualenv salt '*' pip.install <package name> bin_env=/path/to/pip_bin
Complicated CLI Example:
salt '*' pip.install markdown,django editable=git+https://github.com/worldcompany/djangoembed.git#egg=djangoembed upgrade=True no_deps=True
salt.modules.pip.install(pkgs=None, requirements=None, bin_env=None, use_wheel=False, no_use_wheel=False, log=None, proxy=None, timeout=None, editable=None, find_links=None, index_url=None, extra_index_url=None, no_index=False, mirrors=None, build=None, target=None, download=None, download_cache=None, source=None, upgrade=False, force_reinstall=False, ignore_installed=False, exists_action=None, no_deps=False, no_install=False, no_download=False, global_options=None, install_options=None, user=None, cwd=None, pre_releases=False, cert=None, allow_all_external=False, allow_external=None, allow_unverified=None, process_dependency_links=False, saltenv='base', env_vars=None, use_vt=False, trusted_host=None, no_cache_dir=False, extra_args=None, cache_dir=None, no_binary=None, disable_version_check=False, **kwargs)
-
New in version 2018.3.0.
Filter list of installed apps from
freeze
and return True or False ifpkgname
exists in the list of packages installed.Note
If the version of pip available is older than 8.0.3, the packages wheel, setuptools, and distribute will not be reported by this function even if they are installed. Unlike
pip.freeze
, this function always reports the version of pip which is installed.CLI Example:
salt '*' pip.is_installed salt
salt.modules.pip.is_installed(pkgname=None, bin_env=None, user=None, cwd=None)
-
Filter list of installed apps from
freeze
and check to see ifprefix
exists in the list of packages installed.Note
If the version of pip available is older than 8.0.3, the packages
wheel
,setuptools
, anddistribute
will not be reported by this function even if they are installed. Unlikepip.freeze
, this function always reports the version of pip which is installed.CLI Example:
salt '*' pip.list salt
salt.modules.pip.list_(prefix=None, bin_env=None, user=None, cwd=None, env_vars=None, **kwargs)
-
New in version 2017.7.3.
List all available versions of a pip package
- pkg
-
The package to check
- bin_env
-
Path to pip (or to a virtualenv). This can be used to specify the path to the pip to use when more than one Python release is installed (e.g.
/usr/bin/pip-2.7
or/usr/bin/pip-2.6
. If a directory path is specified, it is assumed to be a virtualenv. - include_alpha
-
Include alpha versions in the list
- include_beta
-
Include beta versions in the list
- include_rc
-
Include release candidates versions in the list
- user
-
The user under which to run pip
- cwd
-
Directory from which to run pip
- index_url
-
Base URL of Python Package Index .. versionadded:: 2019.2.0
- extra_index_url
-
Additional URL of Python Package Index .. versionadded:: 2019.2.0
CLI Example:
salt '*' pip.list_all_versions <package name>
salt.modules.pip.list_all_versions(pkg, bin_env=None, include_alpha=False, include_beta=False, include_rc=False, user=None, cwd=None, index_url=None, extra_index_url=None)
-
Check whether or not an upgrade is available for all packages
CLI Example:
salt '*' pip.list_upgrades
salt.modules.pip.list_upgrades(bin_env=None, user=None, cwd=None)
-
Uninstall packages individually or from a pip requirements file
- pkgs
-
comma separated list of packages to install
- requirements
-
Path to requirements file
- bin_env
-
Path to pip (or to a virtualenv). This can be used to specify the path to the pip to use when more than one Python release is installed (e.g.
/usr/bin/pip-2.7
or/usr/bin/pip-2.6
. If a directory path is specified, it is assumed to be a virtualenv. - log
-
Log file where a complete (maximum verbosity) record will be kept
- proxy
-
Specify a proxy in the format
user:[email protected]:port
. Note that theuser:password@
is optional and required only if you are behind an authenticated proxy. If you provide[email protected]:port
then you will be prompted for a password.Note
If the Minion has a globaly configured proxy - it will be used even if no proxy was set here. To explicitly disable proxy for pip you should pass
False
as a value. - timeout
-
Set the socket timeout (default 15 seconds)
- user
-
The user under which to run pip
- cwd
-
Directory from which to run pip
- use_vt
-
Use VT terminal emulation (see output while installing)
CLI Example:
salt '*' pip.uninstall <package name>,<package2 name> salt '*' pip.uninstall requirements=/path/to/requirements.txt salt '*' pip.uninstall <package name> bin_env=/path/to/virtualenv salt '*' pip.uninstall <package name> bin_env=/path/to/pip_bin
salt.modules.pip.uninstall(pkgs=None, requirements=None, bin_env=None, log=None, proxy=None, timeout=None, user=None, cwd=None, saltenv='base', use_vt=False)
-
New in version 2015.5.0.
Upgrades outdated pip packages.
Note
On Windows you can't update salt from pip using salt, so salt will be skipped
Returns a dict containing the changes.
- {'<package>': {'old': '<old-version>',
-
'new': '<new-version>'}}
CLI Example:
salt '*' pip.upgrade
salt.modules.pip.upgrade(bin_env=None, user=None, cwd=None, use_vt=False)
-
New in version 2015.5.0.
Check whether or not an upgrade is available for a given package
CLI Example:
salt '*' pip.upgrade_available <package name>
salt.modules.pip.upgrade_available(pkg, bin_env=None, user=None, cwd=None)
-
New in version 0.17.0.
Returns the version of pip. Use
bin_env
to specify the path to a virtualenv and get the version of pip in that virtualenv.If unable to detect the pip version, returns
None
.Changed in version 3001.1: The
user
parameter was added, to allow specifying the user who runs the version command.CLI Example:
salt '*' pip.version
salt.modules.pip.version(bin_env=None, cwd=None, user=None)
© 2021 SaltStack.
Licensed under the Apache License, Version 2.0.
https://docs.saltproject.io/en/latest/ref/modules/all/salt.modules.pip.html