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 路径	如果与 Ansible Python 解释器不同，则为 pip 可执行文件或路径名的显式名称。例如 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 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	支持： 完全支持	可以在检查模式下运行并返回更改状态预测，而无需修改目标，如果不支持该操作，则会跳过。
diff_mode	支持：不支持	在差异模式下，将返回有关已更改内容（或可能需要在检查模式下更改的内容）的详细信息。
平台	平台： posix	可以对其进行操作的目标操作系统/系列。

注释

注意

• 标记为外部管理的 Python 安装（如 PEP668 中所定义）无法通过 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)

集合链接

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