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 布尔值	传递可编辑标志。 选择 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 需求文件路径，该文件应位于远程系统本地。如果使用 chdir 选项，则文件可以指定为相对路径。
state 字符串	模块的状态。 forcereinstall 选项仅在 Ansible 2.1 及更高版本中可用。 选择 "absent" "forcereinstall" "latest" "present" ← (默认)
umask 字符串	在安装 pip 包之前应用的系统 umask。这在以下情况下非常有用，例如，在默认情况下具有非常严格的 umask 的系统（例如，0077）上安装时，您想 pip install 所有用户都可以使用的包。请注意，这要求您将所需的 umask 模式指定为八进制字符串（例如，0022）。
version 字符串	要安装的 Python 库的版本号，该版本号在 name 参数中指定。
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 更新标记为外部管理（由 PEP668 定义）的 Python 安装。

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

• 尽管 pip 模块使用 Ansible 的 Python 解释器执行，但它会使用 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)

集合链接

• 问题追踪器
• 仓库（源代码）
• 通信