Skip to main content
The pip module manages Python packages using pip, compatible with both global installations and virtualenvs.

​
Functions

​
packages

Install, remove, or update pip packages. 
from pyinfra.operations import pip

pip.packages(
    name="Install Python dependencies",
    packages=["django", "requests"],
)
​
packages
str | list[str]
List of packages to ensure.
​
present
bool
default:true
Whether the packages should be installed.
​
latest
bool
default:false
Whether to upgrade packages without a specified version.
​
requirements
str
Location of requirements file to install/uninstall.
​
pip
str
default:"pip"
Name or path of the pip directory to use.
​
virtualenv
str
Root directory of virtualenv to work in.
​
virtualenv_kwargs
dict
Dictionary of arguments to pass to pip.virtualenv.
​
extra_install_args
str
Additional arguments to the pip install command.
Package versions can be pinned like pip: <pkg>==<version>
If a virtualenv is specified, it will be created if it doesn’t exist. virtualenv_kwargs can control how the env is created.

​
Examples

from pyinfra.operations import pip

pip.packages(
    name="Install pyinfra into a virtualenv",
    packages=["pyinfra"],
    virtualenv="/usr/local/bin/venv",
)

​
virtualenv

Create or remove Python virtualenvs. 
from pyinfra.operations import pip

pip.virtualenv(
    name="Create a virtualenv",
    path="/usr/local/bin/venv",
)
​
path
str
required
Path where the virtualenv should be created.
​
python
str
Python interpreter to use.
​
venv
bool
default:false
Use standard venv module instead of virtualenv.
​
site_packages
bool
default:false
Give access to the global site-packages.
​
always_copy
bool
default:false
Always copy files rather than symlinking.
​
present
bool
default:true
Whether the virtualenv should exist.

​
Examples

from pyinfra.operations import pip

pip.virtualenv(
    name="Create a virtualenv",
    path="/usr/local/bin/venv",
)

​
venv

Create or remove Python virtualenvs using the standard venv module. 
from pyinfra.operations import pip

pip.venv(
    name="Create a venv",
    path="/usr/local/bin/venv",
)
​
path
str
required
Path where the venv should be created.
​
python
str
Python interpreter to use.
​
site_packages
bool
default:false
Give access to the global site-packages.
​
always_copy
bool
default:false
Always copy files rather than symlinking.
​
present
bool
default:true
Whether the venv should exist.
This is a convenience wrapper around pip.virtualenv with venv=True.

​
Common Use Cases

​
Django Application Setup

from pyinfra.operations import pip

# Create virtualenv
pip.virtualenv(
    name="Create Django virtualenv",
    path="/var/www/myapp/venv",
    python="python3.11",
)

# Install Django and dependencies
pip.packages(
    name="Install Django application",
    requirements="/var/www/myapp/requirements.txt",
    virtualenv="/var/www/myapp/venv",
)

​
Data Science Environment

from pyinfra.operations import pip

pip.packages(
    name="Install data science packages",
    packages=[
        "numpy",
        "pandas",
        "matplotlib",
        "scikit-learn",
        "jupyter",
    ],
    virtualenv="/home/user/datascience/venv",
)

​
Development Environment

from pyinfra.operations import pip

# Production dependencies
pip.packages(
    name="Install production dependencies",
    requirements="/app/requirements.txt",
    virtualenv="/app/venv",
)

# Development dependencies
pip.packages(
    name="Install development dependencies",
    requirements="/app/requirements-dev.txt",
    virtualenv="/app/venv",
)

​
Global Tool Installation

from pyinfra.operations import pip

# Install tools globally
pip.packages(
    name="Install global Python tools",
    packages=[
        "black",
        "flake8",
        "mypy",
        "pytest",
    ],
)

​
Pinned Versions for Production

from pyinfra.operations import pip

pip.packages(
    name="Install with pinned versions",
    packages=[
        "django==4.2.0",
        "psycopg2-binary==2.9.5",
        "celery==5.2.7",
        "redis==4.5.4",
    ],
    virtualenv="/app/venv",
)

​
Using Custom PyPI Index

from pyinfra.operations import pip

pip.packages(
    name="Install from private PyPI",
    packages=["mycompany-package"],
    extra_install_args="--index-url https://pypi.mycompany.com/simple",
    virtualenv="/app/venv",
)

​
Python Package Management Tips

Best practices for requirements files:
from pyinfra.operations import pip

# Production requirements
pip.packages(
    name="Install production requirements",
    requirements="/app/requirements/prod.txt",
    virtualenv="/app/venv",
)

# Common pattern:
# requirements/
#   base.txt       # Common dependencies
#   prod.txt       # Production (includes base.txt)
#   dev.txt        # Development (includes base.txt)
Use the latest flag to upgrade packages:
from pyinfra.operations import pip

# Upgrade all packages to latest
pip.packages(
    name="Upgrade all packages",
    packages=["django", "requests", "celery"],
    latest=True,
    virtualenv="/app/venv",
)

# Or upgrade from requirements
pip.packages(
    name="Upgrade from requirements",
    requirements="/app/requirements.txt",
    latest=True,
    virtualenv="/app/venv",
)
Install packages in development mode:
from pyinfra.operations import server

server.shell(
    name="Install package in editable mode",
    commands=[
        "/app/venv/bin/pip install -e /path/to/mypackage",
    ],
)
Access system packages from virtualenv:
from pyinfra.operations import pip

# Create venv with system site-packages
pip.virtualenv(
    name="Create venv with system packages",
    path="/app/venv",
    site_packages=True,
)

# Useful when system packages like numpy are pre-installed
# with optimized binaries
Create virtualenvs with specific Python versions:
from pyinfra.operations import pip

# Python 3.11
pip.virtualenv(
    name="Create Python 3.11 venv",
    path="/app/venv-py311",
    python="python3.11",
)

# Python 3.9
pip.virtualenv(
    name="Create Python 3.9 venv",
    path="/app/venv-py39",
    python="/usr/bin/python3.9",
)

​
Important Notes

Package names are compared using lowercase as per PEP-0426.
When using virtualenv parameter, the virtualenv will be automatically created if it doesn’t exist.
For isolated application installations, consider using pipx instead of global pip installations.

Build docs developers (and LLMs) love

Get started for freeTalk to us