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 要求文件的路径，该文件应位于远程系统本地。如果使用 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	可以对其进行操作的目标操作系统/系列

注释

注意

• 标记为外部管理的 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’ 中指定的包版本 返回： 成功，如果提供了 name 和 version 示例： "2.5.1"
virtualenv 字符串	virtualenv 的路径 返回： 成功，如果提供了 virtualenv 路径 示例： "/tmp/virtualenv"

作者

• Matt Wright (@mattupstate)

集合链接

• 问题追踪器
• 仓库 (源代码)
• 沟通