W3cubDocs

/SaltStack

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.

salt.modules.pip.freeze(bin_env=None, user=None, cwd=None, use_vt=False, env_vars=None, **kwargs)

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, or distribute even if they are installed.

CLI Example:

salt '*' pip.freeze bin_env=/home/code/path/to/virtualenv

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, cache_dir=None, no_binary=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 the user: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.
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/or extra_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 or cache_dir dir
source
Check out editable packages into source 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.

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.is_installed(pkgname=None, bin_env=None, user=None, cwd=None)

New in version 2018.3.0.

Filter list of installed apps from freeze and return True or False if pkgname 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.list_(prefix=None, bin_env=None, user=None, cwd=None, env_vars=None, **kwargs)

Filter list of installed apps from freeze and check to see if prefix 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.list salt

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)

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_upgrades(bin_env=None, user=None, cwd=None)

Check whether or not an upgrade is available for all packages

CLI Example:

salt '*' pip.list_upgrades

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)

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 the user: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.
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.upgrade(bin_env=None, user=None, cwd=None, 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_available(pkg, bin_env=None, user=None, cwd=None)

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.version(bin_env=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.

CLI Example:

salt '*' pip.version

© 2019 SaltStack.
Licensed under the Apache License, Version 2.0.
https://docs.saltstack.com/en/latest/ref/modules/all/salt.modules.pip.html