pipx Operations

The pipx module manages Python applications in isolated environments using pipx.

pipx is designed for installing Python applications, not libraries. Each application is installed in its own isolated environment.

Functions

packages

Install, remove, or update pipx packages.

from pyinfra.operations import pipx

pipx.packages(
    name="Install Python tools",
    packages=["black", "flake8"],
)

str | list[str]

List of packages (PEP-508 format) to ensure.

bool

default:true

Whether the packages should be installed.

bool

default:false

Whether to upgrade packages without a specified version.

str

Additional arguments to the pipx command.

Package versions can be pinned like pip: <pkg>==<version>

pipx supports only one package name at a time, but the operation handles lists automatically.

Example

from pyinfra.operations import pipx

pipx.packages(
    name="Install Python tools",
    packages=["pyinfra"],
)

upgrade_all

Upgrade all pipx packages.

from pyinfra.operations import pipx

pipx.upgrade_all(
    name="Upgrade all pipx packages",
)

ensure_path

Ensure pipx bin directory is in the PATH.

from pyinfra.operations import pipx

pipx.ensure_path(
    name="Ensure pipx is in PATH",
)

This operation checks if the pipx bin directory is already in PATH before making changes.

Common Use Cases

Install Development Tools

from pyinfra.operations import pipx

# Ensure pipx is in PATH
pipx.ensure_path(
    name="Add pipx to PATH",
)

# Install development tools
pipx.packages(
    name="Install Python development tools",
    packages=[
        "black",
        "flake8",
        "mypy",
        "pytest",
        "poetry",
    ],
)

Install with Specific Versions

from pyinfra.operations import pipx

pipx.packages(
    name="Install specific versions",
    packages=[
        "black==23.3.0",
        "ruff==0.0.270",
    ],
)

Keep Tools Updated

from pyinfra.operations import pipx

# Upgrade all installed tools
pipx.upgrade_all(
    name="Upgrade all Python tools",
)

# Or upgrade specific tools
pipx.packages(
    name="Upgrade specific tools",
    packages=["pyinfra", "black"],
    latest=True,
)

Install pyinfra Itself

from pyinfra.operations import pipx

pipx.packages(
    name="Install pyinfra via pipx",
    packages=["pyinfra"],
)

Install with Extras

from pyinfra.operations import pipx

pipx.packages(
    name="Install with extras",
    packages=["httpie[socks]"],
)

Remove Tools

from pyinfra.operations import pipx

pipx.packages(
    name="Remove outdated tools",
    packages=["old-tool"],
    present=False,
)

pipx-Specific Tips

pipx vs pip

When to use pipx:

Installing command-line tools (black, flake8, poetry, etc.)
Applications that should be isolated from other Python environments
Tools you want available system-wide

When to use pip:

Installing libraries for development
Project dependencies in a virtualenv
Packages that don’t provide CLI tools

from pyinfra.operations import pip, pipx

# Use pipx for tools
pipx.packages(
    name="Install CLI tools",
    packages=["black", "pyinfra"],
)

# Use pip for libraries
pip.packages(
    name="Install project dependencies",
    packages=["django", "requests"],
    virtualenv="/app/venv",
)

Injecting Packages

Add packages to existing pipx environments:

from pyinfra.operations import server

# Install a package with additional dependencies
server.shell(
    name="Inject package into pipx environment",
    commands=[
        "pipx inject pyinfra ansible",
    ],
)

Running Applications

Run applications without installing:

from pyinfra.operations import server

# Run a tool temporarily
server.shell(
    name="Run tool with pipx",
    commands=[
        "pipx run black --check .",
    ],
)

List Installed Packages

View installed pipx packages:

from pyinfra.operations import server

server.shell(
    name="List pipx packages",
    commands=["pipx list"],
)

Reinstall Packages

Reinstall packages to fix issues:

from pyinfra.operations import server

server.shell(
    name="Reinstall pipx package",
    commands=["pipx reinstall black"],
)

Best Practices

Use for Global Tools Only

from pyinfra.operations import pipx

# Good: Installing system-wide tools
pipx.packages(
    name="Install system tools",
    packages=[
        "poetry",      # Project management
        "black",       # Code formatter
        "ruff",        # Fast linter
        "pyinfra",     # Infrastructure management
    ],
)

Keep Tools Updated

from pyinfra.operations import pipx

# Regular maintenance
pipx.upgrade_all(
    name="Upgrade all pipx packages monthly",
)

Ensure PATH Configuration

from pyinfra.operations import pipx

# Always ensure PATH is configured
pipx.ensure_path(
    name="Configure pipx PATH",
)

# Then install packages
pipx.packages(
    name="Install tools",
    packages=["black"],
)

Important Notes

Package names are compared using lowercase as per PEP-0426.

pipx requires Python 3.6+ to be installed on the system.

The ensure_path operation modifies the user’s shell configuration files. It should be run before installing packages.

Use pipx run for one-off executions without installing the package permanently.

Overview

Package Managers

Language Packages

Service Management

System Operations

Containers

Databases

Version Control

Security

pipx Operations

Functions

packages

Example

upgrade_all

ensure_path

Common Use Cases

Install Development Tools

Install with Specific Versions

Keep Tools Updated

Install pyinfra Itself

Install with Extras

Remove Tools

pipx-Specific Tips

Best Practices

Important Notes

​Functions

​packages

​Example

​upgrade_all

​ensure_path

​Common Use Cases

​Install Development Tools

​Install with Specific Versions

​Keep Tools Updated

​Install pyinfra Itself

​Install with Extras

​Remove Tools

​pipx-Specific Tips

​Best Practices

​Important Notes

Functions

packages

Example

upgrade_all

ensure_path

Common Use Cases

Install Development Tools

Install with Specific Versions

Keep Tools Updated

Install pyinfra Itself

Install with Extras

Remove Tools

pipx-Specific Tips

Best Practices

Important Notes