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

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

See also: Ansible troubleshooting - Error markupsafe

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

See also: Install Ansible with pip: Python Package Manager Guide (pip install ansible)

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

See also: Ansible apt Module: Install, Remove & Manage Packages on Debian/Ubuntu

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.

Related Articles

• Ansible apt Module Guide • Ansible yum/dnf Module Guide • Ansible command vs shell Module