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/salt@2015.5#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)¶

Return a list of installed packages either globally or in the specified virtualenv

bin_env: path to pip bin or path to virtualenv. If doing an uninstall from the system python and want to use a specific pip bin (pip-2.7, pip-2.6, etc..) just specify the pip bin you want. If uninstalling from a virtualenv, just use the path to the virtualenv (/home/code/path/to/virtualenv/)
user: The user under which to run pip
cwd: Current working directory to run pip from

CLI Example:

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

salt.modules.pip.install(pkgs=None, requirements=None, env=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, no_chown=False, cwd=None, activate=False, pre_releases=False, cert=None, allow_all_external=False, allow_external=None, allow_unverified=None, process_dependency_links=False, __env__=None, saltenv='base', env_vars=None, use_vt=False)¶

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 bin or path to virtualenv. If doing a system install, and want to use a specific pip bin (pip-2.7, pip-2.6, etc..) just specify the pip bin you want. If installing into a virtualenv, just use the path to the virtualenv (/home/code/path/to/virtualenv/)
env: Deprecated, use bin_env now
use_wheel: Prefer wheel archives (requires pip>=1.4)
no_use_wheel: Force to not use wheel archives (requires pip>=1.4)
log: Log file where a complete (maximum verbosity) record will be kept
proxy: Specify a proxy in the form user:passwd@proxy.server:port. Note that the user:password@ is optional and required only if you are behind an authenticated proxy. If you provide user@proxy.server:port then you will be prompted for a password.
timeout: Set the socket timeout (default 15 seconds)
editable: install something editable (i.e. git+https://github.com/worldcompany/djangoembed.git#egg=djangoembed)
find_links: URL to look for packages at
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)
build: Unpack packages into build dir
target: Install packages into target dir
download: Download packages into download instead of installing them
download_cache: Cache downloaded packages in download_cache 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 (use 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
no_chown: When user is given, do not attempt to copy and chown a requirements file
cwd: Current working directory to run pip from
activate: Activates the virtual environment, if given via bin_env, before running install.

Deprecated since version 2014.7.2: If bin_env is given, pip will already be sourced from that virualenv, making activate effectively a noop.
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
use_vt: Use VT terminal emulation (see ouptut while installing)
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.

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.list(prefix=None, bin_env=None, user=None, cwd=None)¶

Filter list of installed apps from freeze and check to see if prefix exists in the list of packages installed.

CLI Example:

salt '*' pip.list salt

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, no_chown=False, cwd=None, __env__=None, saltenv='base', use_vt=False)¶

Uninstall packages with pip

Uninstall packages individually or from a pip requirements file. Uninstall packages globally or from a virtualenv.

pkgs: comma separated list of packages to install
requirements: path to requirements.
bin_env: path to pip bin or path to virtualenv. If doing an uninstall from the system python and want to use a specific pip bin (pip-2.7, pip-2.6, etc..) just specify the pip bin you want. If uninstalling from a virtualenv, just use the path to the virtualenv (/home/code/path/to/virtualenv/)
log: Log file where a complete (maximum verbosity) record will be kept
proxy: Specify a proxy in the form user:passwd@proxy.server:port. Note that the user:password@ is optional and required only if you are behind an authenticated proxy. If you provide user@proxy.server: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
no_chown: When user is given, do not attempt to copy and chown a requirements file
cwd: Current working directory to run pip from
use_vt: Use VT terminal emulation (see ouptut 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

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