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 字符串	模块的状态。 只有在 Ansible 2.1 及更高版本中才可以使用 forcereinstall 选项。 选择 "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	支持：无	在 diff 模式下，将返回有关已更改内容（或在 check_mode 中可能需要更改的内容）的详细信息
platform	平台： posix	可以操作的目标操作系统/系列

说明

注意

• 标记为外部管理的 Python 安装（由 PEP668 定义）无法在不使用虚拟环境或设置 break_system_packages 选项的情况下，通过 pip 版本 >= 23.0.1 更新。

• 如果指定了 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)

合集链接

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