ansible.builtin.pip 模块 – 管理 Python 库依赖项

注意

此模块是 ansible-core 的一部分，包含在所有 Ansible 安装中。在大多数情况下，即使不指定集合关键字，您也可以使用简短的模块名称 pip。但是，我们建议您使用完全限定集合名称 (FQCN) ansible.builtin.pip，以便轻松链接到模块文档并避免与可能具有相同模块名称的其他集合冲突。

概要

• 管理 Python 库依赖项。要使用此模块，需要以下键之一： name 或 requirements。

要求

在执行此模块的主机上需要以下要求。

• pip

• virtualenv

• setuptools 或 packaging

参数

参数	注释
break_system_packages 布尔值 在 ansible-core 2.17 中添加	允许 pip 修改由 PEP 668 定义的外部管理的 Python 安装。 在现代系统上，在虚拟环境之外安装软件包时，通常需要这样做。 选项 false ←（默认） true
chdir 路径	在运行命令之前，先进入此目录。
editable 布尔值	传递可编辑标志。 选项 false ←（默认） true
executable 路径	如果与 Ansible Python 解释器不同，则 pip 可执行文件的显式可执行文件或路径名。例如，如果系统中有 Python 2.7 和 3.3 安装，并且您想为 Python 3.3 安装运行 pip，则为 pip3.3。 与 virtualenv 互斥（在 2.1 中添加）。 不影响 Ansible Python 解释器。 必须为 Ansible Python 解释器和此选项指定的 Python 版本安装 setuptools 包。
extra_args 字符串	传递给 pip 的额外参数。
name 列表 / 元素=字符串	要安装的 Python 库的名称或远程包的 url(bzr+、hg+、git+、svn+)。 它可以是列表（自 2.2 起）并包含版本说明符（自 2.7 起）。
requirements 字符串	pip requirements 文件的路径，该文件应位于远程系统的本地。如果使用 chdir 选项，则可以将文件指定为相对路径。
state 字符串	模块的状态。 forcereinstall 选项仅在 Ansible 2.1 及更高版本中可用。 选项 "absent" "forcereinstall" "latest" "present" ←（默认）
umask 字符串	在安装 pip 包之前要应用的系统 umask。例如，当在默认情况下具有非常严格的 umask（例如，0077）的系统上安装，并且您希望 pip install 所有用户都将使用的软件包时，此功能很有用。请注意，这需要您将所需的 umask 模式指定为八进制字符串（例如，0022）。
version 字符串	要安装的在 name 参数中指定的 Python 库的版本号。
virtualenv 路径	要安装到的 *virtualenv* 目录的可选路径。它不能与 executable 参数一起指定（在 2.1 中添加）。如果 virtualenv 不存在，则会在安装软件包之前创建它。可选的 virtualenv_site_packages、virtualenv_command 和 virtualenv_python 选项会影响 virtualenv 的创建。
virtualenv_command 路径	用于创建虚拟环境的命令或命令的路径名。例如 pyvenv、virtualenv、virtualenv2、~/bin/virtualenv、/usr/local/bin/virtualenv。 默认： "virtualenv"
virtualenv_python 字符串	用于创建虚拟环境的 Python 可执行文件。例如 python3.12、python2.7。如果未指定，则使用用于运行 ansible 模块的 Python 版本。当 virtualenv_command 使用 pyvenv 或 -m venv 模块时，不应使用此参数。
virtualenv_site_packages 布尔值	虚拟环境是否将从全局 site-packages 目录继承软件包。请注意，如果已存在的虚拟环境更改此设置，它将不会产生任何影响，必须删除环境并重新创建。 选项 false ←（默认） true

属性

属性	支持	描述
check_mode	支持：完全	可以在 check_mode 中运行并返回更改状态预测，而无需修改目标，如果不支持，则会跳过该操作。
diff_mode	支持：无	当处于差异模式时，将返回有关已更改内容（或在 check_mode 中可能需要更改的内容）的详细信息
platform	平台： posix	可以操作的目标操作系统/系列

注释

注意

• 根据 PEP668 定义，标记为外部管理的 Python 安装无法通过 pip 版本 >= 23.0.1 更新，除非使用虚拟环境或设置 break_system_packages 选项。

• 如果指定了 virtualenv 参数且需要创建 virtualenv，则必须在远程主机上安装 virtualenv (http://www.virtualenv.org/)。

• 尽管它使用 Ansible Python 解释器执行，但 pip 模块会调用 shell 来运行实际的 pip 命令，因此它可以根据你使用 executable 指定的任何 pip 版本。默认情况下，它使用 Ansible Python 解释器的 pip 版本。例如，Python 3 上使用 pip3，Python 2 上使用 pip2 或 pip。

• Ansible 使用的解释器 (参见 ansible_python_interpreter) 需要 setuptools 包，无论使用 executable 选项设置的 pip 版本如何。

示例

- name: Install bottle python package
  ansible.builtin.pip:
    name: bottle

- name: Install bottle python package on version 0.11
  ansible.builtin.pip:
    name: bottle==0.11

- name: Install bottle python package with version specifiers
  ansible.builtin.pip:
    name: bottle>0.10,<0.20,!=0.11

- name: Install multi python packages with version specifiers
  ansible.builtin.pip:
    name:
      - django>1.11.0,<1.12.0
      - bottle>0.10,<0.20,!=0.11

- name: Install python package using a proxy
  ansible.builtin.pip:
    name: six
  environment:
    http_proxy: 'http://127.0.0.1:8080'
    https_proxy: 'https://127.0.0.1:8080'

# You do not have to supply '-e' option in extra_args
- name: Install MyApp using one of the remote protocols (bzr+,hg+,git+,svn+)
  ansible.builtin.pip:
    name: svn+http://myrepo/svn/MyApp#egg=MyApp

- name: Install MyApp using one of the remote protocols (bzr+,hg+,git+)
  ansible.builtin.pip:
    name: git+http://myrepo/app/MyApp

- name: Install MyApp from local tarball
  ansible.builtin.pip:
    name: file:///path/to/MyApp.tar.gz

- name: Install bottle into the specified (virtualenv), inheriting none of the globally installed modules
  ansible.builtin.pip:
    name: bottle
    virtualenv: /my_app/venv

- name: Install bottle into the specified (virtualenv), inheriting globally installed modules
  ansible.builtin.pip:
    name: bottle
    virtualenv: /my_app/venv
    virtualenv_site_packages: yes

- name: Install bottle into the specified (virtualenv), using Python 2.7
  ansible.builtin.pip:
    name: bottle
    virtualenv: /my_app/venv
    virtualenv_command: virtualenv-2.7

- name: Install bottle within a user home directory
  ansible.builtin.pip:
    name: bottle
    extra_args: --user

- name: Install specified python requirements
  ansible.builtin.pip:
    requirements: /my_app/requirements.txt

- name: Install specified python requirements in indicated (virtualenv)
  ansible.builtin.pip:
    requirements: /my_app/requirements.txt
    virtualenv: /my_app/venv

- name: Install specified python requirements and custom Index URL
  ansible.builtin.pip:
    requirements: /my_app/requirements.txt
    extra_args: -i https://example.com/pypi/simple

- name: Install specified python requirements offline from a local directory with downloaded packages
  ansible.builtin.pip:
    requirements: /my_app/requirements.txt
    extra_args: "--no-index --find-links=file:///my_downloaded_packages_dir"

- name: Install bottle for Python 3.3 specifically, using the 'pip3.3' executable
  ansible.builtin.pip:
    name: bottle
    executable: pip3.3

- name: Install bottle, forcing reinstallation if it's already installed
  ansible.builtin.pip:
    name: bottle
    state: forcereinstall

- name: Install bottle while ensuring the umask is 0022 (to ensure other users can use it)
  ansible.builtin.pip:
    name: bottle
    umask: "0022"
  become: True

- name: Run a module inside a virtual environment
  block:
    - name: Ensure the virtual environment exists
      pip:
        name: psutil
        virtualenv: "{{ venv_dir }}"
        # On Debian-based systems the correct python*-venv package must be installed to use the `venv` module.
        virtualenv_command: "{{ ansible_python_interpreter }} -m venv"

    - name: Run a module inside the virtual environment
      wait_for:
        port: 22
      vars:
        # Alternatively, use a block to affect multiple tasks, or use set_fact to affect the remainder of the playbook.
        ansible_python_interpreter: "{{ venv_python }}"

  vars:
    venv_dir: /tmp/pick-a-better-venv-path
    venv_python: "{{ venv_dir }}/bin/python"

返回值

常见的返回值记录在 此处，以下是此模块独有的字段

键	描述
cmd 字符串	模块使用的 pip 命令 返回： 成功 示例： "pip2 install ansible six"
name 列表 / 元素=字符串	pip 目标 Python 模块列表 返回： 成功 示例： ["ansible", "six"]
requirements 字符串	requirements 文件的路径 返回： 如果提供了 requirements 文件，则返回成功 示例： "/srv/git/project/requirements.txt"
version 字符串	在 'name' 中指定的软件包版本 返回： 如果提供了名称和版本，则返回成功 示例： "2.5.1"
virtualenv 字符串	virtualenv 的路径 返回： 如果提供了 virtualenv 路径，则返回成功 示例： "/tmp/virtualenv"

作者

• Matt Wright (@mattupstate)

集合链接

• 问题跟踪器
• 存储库（源代码）
• 通信