Skip to main content
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"],
)
​
packages
str | list[str]
List of packages (PEP-508 format) to ensure.
​
present
bool
default:true
Whether the packages should be installed.
​
latest
bool
default:false
Whether to upgrade packages without a specified version.
​
extra_args
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

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",
)
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",
    ],
)
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 .",
    ],
)
View installed pipx packages:
from pyinfra.operations import server

server.shell(
    name="List pipx packages",
    commands=["pipx list"],
)
Reinstall packages to fix issues:
from pyinfra.operations import server

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

​
Best Practices

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
    ],
)

from pyinfra.operations import pipx

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

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.

Build docs developers (and LLMs) love

Get started for freeTalk to us