pip

pip#

Модуль ansible.builtin.pip управляет пакетами Python с помощью менеджера пакетов PIP.

Особенности работы#

Для корректной работы модуля на управляемом узле должно быть установлено следующее ПО:

  • pip;

  • virtualenv (только если используются параметры virtualenv, virtualenv_command, virtualenv_python или virtualenv_site_packages);

  • setuptools или packaging.

Инсталляции Python, отмеченные как управляемые внешне (согласно PEP 668), нельзя обновить при помощи PIP версии 23.0.1 или выше без использования виртуального окружения или параметра break_system_packages.

Независимо от значения параметра executable, в окружение интерпретатора Python, используемого Ansible, должен быть установлен пакет setuptools.

Параметры#

Модуль принимает следующие параметры:

break_system_packages#

Разрешение на операции с пакетами Python, установленными на уровне системы. Как правило, такое разрешение требуется при установке пакетов без использования виртуальных окружений.

Подробности см. в PEP 668.

Возможные значения:

  • false – операции запрещены;

  • true – операции разрешены.

    Предупреждение

    Замена или удаление пакетов Python, установленных на уровне ОС, могут нарушить ее функционирование.

Значение по умолчанию: false.

chdir#

Путь к каталогу, в который необходимо перейти перед выполнением команды.

editable#

Установка пакета в режиме разработчика (разрешено редактирование кода установленных модулей).

Возможные значения:

  • false – редактирование запрещено;

  • true – редактирование разрешено.

Значение по умолчанию: false.

executable#

Название исполняемого файла PIP или полный путь к нему.

Например, в ОС могут быть установлены интерпретаторы Python 3.9 и Python 3.11. При этом по умолчанию используется PIP из окружения интерпретатора Python 3.9. Чтобы использовать PIP из окружения интерпретатора Python 3.11, присвойте параметру значение pip3.11 или полный путь к исполняемому файлу, например, /usr/bin/pip3.11.

Примечание

  • Этот параметр не влияет на настройки интерпретатора Python, используемого Ansible.

  • Пакет setuptools должен быть установлен и в окружении интерпретатора Python, используемого Ansible, и в фактически используемое окружение.

Этот параметр нельзя использовать одновременно с ``virtualenv``.

Значение по умолчанию: версия PIP из окружения интерпретатора Python, в котором работает Ansible.

extra_args#

Дополнительные параметры, передаваемые PIP.

name#

Значение этого параметра обязательно для заполнения, если не задан параметр ``requirements``.

Название пакета Python или ссылка на него. Также поддерживаются списки и спецификации версий.

requirements#

Значение этого параметра обязательно для заполнения, если не задан параметр ``name``.

Путь к файлу со списком зависимостей в файловой системе управляемого узла. Если используется параметр chdir, путь должен быть относительным.

state#

Требуемое состояние пакета.

Возможные значения:

  • absent – отсутствует;

  • forcereinstall – переустановлен принудительно;

  • latest – установлена самая новая версия;

  • present – установлена любая версия из доступных.

Значение по умолчанию: present.

umask#

Маска (umask) учетной записи пользователя, применяемая перед установкой пакета с помощью PIP. Использование этого параметра может быть полезным в том случае, когда значение umask по умолчанию сильно ограничивает режим доступа к создаваемым файлам. Например, если значение по умолчанию равно 0077, а устанавливаемые пакеты должны быть доступны всем пользователям, присвойте этому параметру значение 0766.

Важно

Значение этого параметра необходимо задавать в восьмеричной системе счисления.

version#

Версия пакета, указанного в значении параметра name.

virtualenv#

Путь к каталогу виртуального окружения, созданного с помощью virtualenv. Если указанное окружение не существует, модуль создаст его. Для управления настройками создаваемого окружения используйте параметры virtualenv_command, virtualenv_python и virtualenv_site_packages.

Этот параметр нельзя использовать одновременно с ``executable``.

virtualenv_command#

Команда или путь к исполняемому файлу, используемые для создания виртуального окружения.

Значение по умолчанию: virtualenv.

virtualenv_python#

Интерпретатор Python, используемый для создаваемого виртуального окружения.

Примечание

Этот параметр нельзя использовать, если параметру virtualenv_command задано значение pyvenv или -m venv.

Значение по умолчанию: интерпретатор, используемый Ansible.

virtualenv_site_packages#

Разрешение на доступ из создаваемого виртуального окружения к пакетам Python, установленным на уровне ОС.

Важно

Значение этой настройки не влияет на уже существующие виртуальные окружения. Чтобы изменить доступ виртуального окружения к пакетам Python, установленным на уровне ОС, удалите окружение и создайте его заново.

Возможные значения:

  • false – виртуальное окружение не имеет доступа к пакетам, установленным на уровне ОС;

  • true – виртуальному окружению доступны пакеты, установленные на уровне ОС.

Значение по умолчанию: false.

Возвращаемые значения#

В этом списке указаны только возвращаемые значения, специфичные для модуля ansible.builtin.pip.

  • cmd – команда, использованная модулем для вызова PIP.

    Условия: успешное завершение.

  • name – список названий пакетов, обработанных PIP.

    Условия: успешное завершение.

  • requirements – путь к файлу со списком зависимостей.

    Условия: успешное завершение и непустое значение параметра requirements.

  • version – версия пакета, указанного в name.

    Условия: успешное завершение, указание названия и версии пакета.

  • virtualenv – путь к виртуальному окружению.

    Условия: успешное завершение и непустое значение параметра virtualenv.

Атрибуты#

Атрибуты определяют функции Ansible, которые может использовать модуль.

Атрибут

Описание

check_mode

Модуль работает в режиме проверки (check_mode) в полном объеме. Режим проверки позволяет узнать что произойдет при выполнении указанных действий с виртуальными окружениями и пакетами.

diff_mode

Модуль не поддерживает режим сравнения.

platform

Модуль поддерживает только POSIX-совместимые ОС.

Примеры#

Для изучения возможностей модуля ознакомьтесь с приведенными ниже примерами.

Установка пакета в системное окружение#

Следующий пример демонстрирует установку пакета jinja2 в системное окружение Astra Linux Special Edition 1.8:

---
# ...
  tasks:
    - name: Install package jinja2
      ansible.builtin.pip:
        break_system_packages: true
        name: jinja2
        state: latest

Установка пакета указанной версии#

Следующий пример демонстрирует установку пакета jinja2 версии 3.1.6 в системное окружение Astra Linux Special Edition 1.8:

---
# ...
  tasks:
    - name: Install package jinja2
      ansible.builtin.pip:
        break_system_packages: true
        name: jinja2==3.1.6
        state: present

Установка нескольких пакетов#

Следующий пример демонстрирует установку нескольких пакетов в системное окружение Astra Linux Special Edition 1.8:

---
# ...
  tasks:
    - name: Install many packages
      ansible.builtin.pip:
        name:
          - flask
          - psycopg2
          - pillow
        break_system_packages: true
        state: present

Установка по ссылке#

Следующий пример демонстрирует загрузку и установку пакета по ссылке:

---
# ...
  tasks:
    - name: Install package
      ansible.builtin.pip:
        name: git+https://git.example.com/package.git
        state: present

Установка пакета в виртуальное окружение#

Следующий пример демонстрирует установку пакетов в виртуальное окружение. Если окружение не существует, оно будет создано с помощью virtualenv.

---
# ...
  tasks:
    - name: Install packages
      ansible.builtin.pip:
        name:
          - django
          - pillow
          - psycopg2
        state: present
        virtualenv: /opt/app/.venv

Установка пакета в виртуальное окружение venv#

Следующий пример демонстрирует установку пакетов в виртуальное окружение, созданное с помощью модуля Python venv:

---
# ...
  tasks:
    - name: Install packages
      ansible.builtin.pip:
        name:
          - django
          - pillow
          - psycopg2
        state: present
        virtualenv: /var/www/app/.venv
        virtualenv_command: "{{ ansible_python_interpreter }} -m venv"

Установка пакетов из списка зависимостей#

Следующий пример демонстрирует установку пакетов, перечисленных в файле requirements.txt:

---
# ...
  tasks:
    - name: Install requirements
      ansible.builtin.pip:
        requirements: /tmp/requirements.txt
        state: present
        virtualenv: /opt/app/.venv

Дополнительные аргументы вызова PIP#

Следующий пример демонстрирует вызов PIP с дополнительными аргументами:

---
# ...
  tasks:
    - name: Install package from own repository
      ansible.builtin.pip:
        name: own-package==1.0.2
        extra_args: "-i https://pypi.example.com/packages"
        state: present