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

注意

此模块是 ansible-core 的一部分，包含在所有 Ansible 安装中。在大多数情况下，即使不指定 collections 关键字，您也可以使用简短的模块名称 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 路径	在运行命令之前 cd 到此目录
editable 布尔值	传递 editable 标志。 选项 false ← (默认) true
executable 路径	pip 可执行文件的显式可执行文件或路径名，如果与 Ansible Python 解释器不同。例如 pip3.3，如果系统中有 Python 2.7 和 3.3 安装，并且您想为 Python 3.3 安装运行 pip。 与 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 安装所有用户都可以使用的软件包时，这很有用。请注意，这需要您将所需的 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	可以对其进行操作的目标操作系统/系列

注释

注意

• 没有使用虚拟环境或设置 break_system_packages 选项，pip 版本 >= 23.0.1 无法更新标记为外部管理的 Python 安装（如 PEP668 中定义）。

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

集合链接

• 问题跟踪器
• 存储库（来源）
• 通讯