Ansible pip Module: Install Python Packages & Libraries (Guide)

By Luca Berton · Published 2024-01-01 · Category: installation

How to install Python packages with Ansible pip module (ansible.builtin.pip). Install from PyPI, requirements.txt, virtualenvs.

The ansible.builtin.pip module installs Python packages using pip on managed hosts. It handles individual packages, requirements files, virtual environments, and version pinning.

Install a Package

- name: Install Flask
  ansible.builtin.pip:
    name: flask
    state: present

Install Multiple Packages

- name: Install Python packages
  ansible.builtin.pip:
    name:
      - flask
      - gunicorn
      - celery
      - redis
    state: present

Install Specific Version

# Exact version
- ansible.builtin.pip:
    name: flask==3.1.0

# Minimum version
- ansible.builtin.pip:
    name: "flask>=3.0,<4.0"

# Latest version
- ansible.builtin.pip:
    name: flask
    state: latest

Install from requirements.txt

# Copy requirements file first
- name: Copy requirements
  ansible.builtin.copy:
    src: requirements.txt
    dest: /opt/myapp/requirements.txt

- name: Install from requirements
  ansible.builtin.pip:
    requirements: /opt/myapp/requirements.txt

Virtual Environments

# Create venv and install packages
- name: Install in virtualenv
  ansible.builtin.pip:
    name:
      - flask
      - gunicorn
    virtualenv: /opt/myapp/venv
    virtualenv_command: python3 -m venv

# Install from requirements in venv
- name: Install requirements in venv
  ansible.builtin.pip:
    requirements: /opt/myapp/requirements.txt
    virtualenv: /opt/myapp/venv

Remove a Package

- name: Remove package
  ansible.builtin.pip:
    name: flask
    state: absent

Use a Specific pip Executable

# Use pip3 explicitly
- ansible.builtin.pip:
    name: flask
    executable: pip3

# Use pip from a specific path
- ansible.builtin.pip:
    name: flask
    executable: /usr/local/bin/pip3.11

Key Parameters

Parameter	Default	Description
`name`	—	Package name(s) with optional version
`state`	present	`present`, `absent`, `latest`, `forcereinstall`
`requirements`	—	Path to requirements.txt
`virtualenv`	—	Path to virtualenv
`virtualenv_command`	virtualenv	Command to create venv
`executable`	—	pip executable to use
`extra_args`	—	Extra pip arguments
`editable`	false	Install in editable mode

Practical Examples

Deploy Python Application

- name: Deploy Python app
  hosts: appservers
  become: true
  vars:
    app_dir: /opt/myapp
    venv_dir: "{{ app_dir }}/venv"

  tasks:
    - name: Install system Python
      ansible.builtin.apt:
        name:
          - python3
          - python3-pip
          - python3-venv
        state: present

    - name: Create app directory
      ansible.builtin.file:
        path: "{{ app_dir }}"
        state: directory
        owner: appuser
        mode: '0755'

    - name: Copy application code
      ansible.builtin.copy:
        src: app/
        dest: "{{ app_dir }}/"
        owner: appuser

    - name: Install dependencies in virtualenv
      ansible.builtin.pip:
        requirements: "{{ app_dir }}/requirements.txt"
        virtualenv: "{{ venv_dir }}"
        virtualenv_command: python3 -m venv
      become_user: appuser

Install pip Itself

# Ensure pip is installed
- name: Install pip
  ansible.builtin.apt:
    name: python3-pip
    state: present

# Upgrade pip
- name: Upgrade pip
  ansible.builtin.pip:
    name: pip
    state: latest
    extra_args: --upgrade

Install from Git Repository

- name: Install from Git
  ansible.builtin.pip:
    name: "git+https://github.com/user/repo.git@v1.2.3"

# Install in editable mode (development)
- name: Install editable package
  ansible.builtin.pip:
    name: /opt/myapp
    editable: true
    virtualenv: /opt/myapp/venv

Install with Extra Index

- name: Install from private PyPI
  ansible.builtin.pip:
    name: my-private-package
    extra_args: "--index-url https://pypi.private.example.com/simple"

Freeze and Restore

# Capture current state
- name: Freeze installed packages
  ansible.builtin.command: /opt/myapp/venv/bin/pip freeze
  register: frozen
  changed_when: false

- name: Save freeze output
  ansible.builtin.copy:
    content: "{{ frozen.stdout }}"
    dest: /opt/myapp/requirements.frozen.txt

FAQ

How do I install pip on a fresh server?

For Debian/Ubuntu: apt: name=python3-pip. For RHEL: dnf: name=python3-pip. The pip module requires pip to already be installed on the target host.

Should I use virtualenv or install system-wide?

Always use virtualenvs for applications — it prevents dependency conflicts between projects and with system packages. Only install system-wide for system tools or Ansible's own dependencies.

Why does pip fail with "externally-managed-environment"?

Python 3.11+ on Debian/Ubuntu blocks system-wide pip installs (PEP 668). Use virtualenv parameter or add extra_args: "--break-system-packages" (not recommended for production).

How do I handle packages that need compilation?

Install build dependencies first:

- ansible.builtin.apt:
    name: [python3-dev, gcc, libffi-dev]
    state: present

- ansible.builtin.pip:
    name: cryptography

Conclusion

Use the pip module with virtualenv for application deployments, requirements for reproducible installs, and version pinning for production stability. Always install system pip first via the OS package manager before using the pip module.

Category: installation

Browse all Ansible tutorials · AnsiblePilot Home

AnsiblePilot — Master Ansible Automation

Popular Topics

About Luca Berton