# salt.modules.pip

Install Python packages with pip to either the system or a virtualenv

## Windows Support

Added 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.

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

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, extra_args=None, cache_dir=None, no_binary=None, disable_version_check=False, **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. If this file doesn't exist and the parent directory is writeable, it will be created.

  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.

    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/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.

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

  Added in version 2018.3.0.

  Changed in version 3006.0.

  Filter list of installed modules and return True if `pkgname` exists in the list of packages 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)

  Changed in version 3006.0.

  Output list of installed apps from `pip list` in JSON format and check to see if `prefix` exists in the list of packages installed.

  Note

  If the version of pip available is older than 9.0.0, parsing the `freeze` function output will be used to determine the name and version of installed modules.

  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)

  Added 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_freeze_parse(prefix=None, bin_env=None, user=None, cwd=None, env_vars=None, **kwargs)

  Added in version 3006.0.

  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_freeze_parse 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, 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: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.

    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.upgrade(bin_env=None, user=None, cwd=None, use_vt=False)

  Added 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)

  Added 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, cwd=None, user=None)

  Added 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