Convert Figma logo to code with AI

pypa logopipx

Install and Run Python Applications in Isolated Environments

10,321
411
10,321
115
View on GitHub

Top Related Projects

pypa's avatar

pip

9,503

The Python package installer

conda's avatar

conda

6,398

A system-level, binary package and environment manager running on all major operating systems and platforms.

python-poetry's avatar

poetry

31,032

Python packaging and dependency management made easy

pdm-project's avatar

pdm

7,771

A modern Python package and dependency manager supporting the latest PEP standards

mitsuhiko's avatar

pipsi

2,002

pip script installer

pyenv's avatar

pyenv

39,014

Simple Python version management

Quick Overview

pipx is a tool designed to install and run Python applications in isolated environments. It allows users to easily install and manage Python packages globally while keeping them separate from system-wide packages, providing a convenient way to use Python CLI tools without affecting other Python installations.

Pros

  • Installs Python packages in isolated environments, preventing conflicts with system packages
  • Allows easy global access to Python CLI tools without polluting the system Python installation
  • Supports upgrading and uninstalling packages cleanly
  • Provides a simple interface for managing Python applications

Cons

  • Limited to Python packages with CLI entry points
  • May have slower initial installation times compared to direct pip installations
  • Requires Python 3.6+ to run
  • Not suitable for managing libraries or packages used as dependencies in other projects

Getting Started

To install pipx, use pip:

python3 -m pip install --user pipx
python3 -m pipx ensurepath

To install a Python package using pipx:

pipx install package_name

To run a Python package without installing it:

pipx run package_name

To list installed packages:

pipx list

To upgrade an installed package:

pipx upgrade package_name

To uninstall a package:

pipx uninstall package_name

Competitor Comparisons

pypa logo

pip

9,503

The Python package installer

Pros of pip

  • Widely adopted and well-established package manager for Python
  • Supports installation of packages from various sources (PyPI, VCS, local files)
  • Extensive documentation and community support

Cons of pip

  • Installs packages globally, which can lead to conflicts between projects
  • Doesn't provide easy isolation for command-line applications
  • Requires manual management of virtual environments for project isolation

Code comparison

pip:

pip install package_name

pipx:

pipx install package_name

Key differences

  • pipx is designed specifically for installing and running Python applications in isolated environments
  • pip is a general-purpose package manager, while pipx focuses on command-line tools
  • pipx automatically creates and manages virtual environments for each installed application

Use cases

pip:

  • Installing dependencies for Python projects
  • Managing packages within existing virtual environments

pipx:

  • Installing command-line applications globally without conflicts
  • Running Python applications in isolated environments

Conclusion

While pip remains the primary tool for managing Python packages, pipx offers a specialized solution for installing and running Python applications in isolated environments, particularly useful for command-line tools.

conda logo

conda

6,398

A system-level, binary package and environment manager running on all major operating systems and platforms.

Pros of conda

  • Manages both Python and non-Python packages
  • Creates isolated environments with their own dependencies
  • Supports multiple programming languages (not just Python)

Cons of conda

  • Larger installation size and slower package resolution
  • Can be more complex to use for simple Python package management
  • May have conflicts with system-wide Python installations

Code comparison

conda:

conda create -n myenv python=3.8
conda activate myenv
conda install package_name

pipx:

pipx install package_name
pipx run package_name

Summary

conda is a comprehensive package and environment management system that supports multiple languages and complex dependency structures. It's ideal for data science and scientific computing projects that require specific package versions and isolated environments.

pipx, on the other hand, is focused on installing and running Python applications in isolated environments. It's simpler to use and more lightweight, making it a good choice for users who primarily work with Python and want to quickly install and run Python applications without worrying about complex environment management.

Choose conda for more complex projects with diverse language requirements, and pipx for straightforward Python application management and execution.

python-poetry logo

poetry

31,032

Python packaging and dependency management made easy

Pros of Poetry

  • Provides comprehensive dependency management and packaging in a single tool
  • Offers a lockfile for reproducible builds and dependency resolution
  • Supports virtual environments out of the box

Cons of Poetry

  • Steeper learning curve for beginners compared to simpler tools
  • Can be slower for large projects due to its comprehensive approach
  • May conflict with other package management tools in complex setups

Code Comparison

Poetry:

[tool.poetry]
name = "my-project"
version = "0.1.0"
dependencies = {
    "requests": "^2.25.1"
}

Pipx:

# No equivalent configuration file
# Pipx is used to install and run Python applications in isolated environments
pipx install requests

Poetry focuses on project-level dependency management and packaging, while Pipx is designed for installing and running Python applications in isolated environments. Poetry offers more comprehensive project management features, but Pipx excels in simplicity for running isolated Python tools.

pdm-project logo

pdm

7,771

A modern Python package and dependency manager supporting the latest PEP standards

Pros of PDM

  • Offers a more comprehensive package management solution, including dependency resolution and virtual environment management
  • Supports PEP 582 for simpler dependency management without virtual environments
  • Provides a lockfile for reproducible builds and better dependency tracking

Cons of PDM

  • Steeper learning curve due to more features and complexity
  • May be overkill for simple projects or users who prefer minimal tooling
  • Less widespread adoption compared to pipx, potentially leading to fewer community resources

Code Comparison

PDM:

pdm init
pdm add requests
pdm run python main.py

pipx:

pipx install requests
pipx run requests

Key Differences

  • PDM is a full-featured package and dependency manager, while pipx focuses on installing and running Python applications in isolated environments
  • PDM manages project-level dependencies, whereas pipx is designed for global, isolated application installations
  • PDM offers more advanced features like lockfiles and PEP 582 support, while pipx prioritizes simplicity and ease of use for running Python applications

Both tools serve different purposes and can be complementary in a Python developer's toolkit, with PDM being more suitable for complex project management and pipx excelling at running isolated Python applications.

mitsuhiko logo

pipsi

2,002

pip script installer

Pros of pipsi

  • Simpler and more lightweight installation process
  • Supports older Python versions (2.6+)
  • Allows for easy uninstallation of packages and their dependencies

Cons of pipsi

  • No longer actively maintained (last commit in 2018)
  • Lacks some advanced features present in pipx
  • May have compatibility issues with newer Python versions and packages

Code Comparison

pipsi:

def install_package(package, python=None, editable=False, system_site_packages=False):
    package, install_args = parse_package_spec(package)
    venv_path = get_package_path(package)
    if os.path.isdir(venv_path):
        click.echo('%s is already installed' % package)
        return

pipx:

def install(
    package_spec: str,
    python: str = DEFAULT_PYTHON,
    pip_args: List[str] = [],
    venv_args: List[str] = [],
    force: bool = False,
    include_dependencies: bool = False,
    suffix: str = "",
) -> ExitCode:
    """Install a package"""
    venv_dir = constants.PIPX_LOCAL_VENVS / (package_spec.split("==")[0] + suffix)

Both tools aim to simplify the installation of Python packages in isolated environments. However, pipx is more actively maintained and offers additional features, making it generally preferred for current projects. pipsi may still be useful for older Python versions or simpler use cases.

pyenv logo

pyenv

39,014

Simple Python version management

Pros of pyenv

  • Manages multiple Python versions on a single system
  • Allows switching between Python versions per project or globally
  • Supports installation of Python versions from source

Cons of pyenv

  • More complex setup and configuration process
  • Limited to Python version management, not package isolation
  • Requires manual installation of packages for each Python version

Code Comparison

pyenv:

pyenv install 3.9.0
pyenv global 3.9.0
python --version

pipx:

pipx install package_name
pipx run package_name

Summary

pyenv focuses on managing multiple Python versions, allowing users to switch between different versions easily. It's ideal for developers working on projects requiring specific Python versions.

pipx, on the other hand, is designed for installing and running Python applications in isolated environments. It's more suitable for end-users who want to use Python applications without worrying about version conflicts.

While pyenv provides granular control over Python versions, pipx offers a simpler solution for running Python applications in isolation. The choice between the two depends on the user's specific needs and use case.

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

pipx — Install and Run Python Applications in Isolated Environments

image PyPI version

Documentation: https://pipx.pypa.io

Source Code: https://github.com/pypa/pipx

For comparison to other tools including pipsi, see Comparison to Other Tools.

Install pipx

[!WARNING]

It is not recommended to install pipx via pipx. If you'd like to do this anyway, take a look at the pipx-in-pipx project and read about the limitations there.

On macOS

brew install pipx
pipx ensurepath
sudo pipx ensurepath --global # optional to allow pipx actions with --global argument

Upgrade pipx with brew update && brew upgrade pipx.

On Linux

  • Ubuntu 23.04 or above
sudo apt update
sudo apt install pipx
pipx ensurepath
sudo pipx ensurepath --global # optional to allow pipx actions with --global argument
  • Fedora:
sudo dnf install pipx
pipx ensurepath
sudo pipx ensurepath --global # optional to allow pipx actions with --global argument
  • Arch:
sudo pacman -S python-pipx
pipx ensurepath
sudo pipx ensurepath --global # optional to allow pipx actions with --global argument
  • Using pip on other distributions:
python3 -m pip install --user pipx
python3 -m pipx ensurepath
sudo pipx ensurepath --global # optional to allow pipx actions with --global argument

Upgrade pipx with python3 -m pip install --user --upgrade pipx.

On Windows

scoop install pipx
pipx ensurepath

Upgrade pipx with scoop update pipx.

  • install via pip (requires pip 19.0 or later)
# If you installed python using Microsoft Store, replace `py` with `python3` in the next line.
py -m pip install --user pipx

It is possible (even most likely) the above finishes with a WARNING looking similar to this:

WARNING: The script pipx.exe is installed in `<USER folder>\AppData\Roaming\Python\Python3x\Scripts` which is not on PATH

If so, go to the mentioned folder, allowing you to run the pipx executable directly. Enter the following line (even if you did not get the warning):

.\pipx.exe ensurepath

This will add both the above mentioned path and the %USERPROFILE%\.local\bin folder to your search path. Restart your terminal session and verify pipx does run.

Upgrade pipx with py -m pip install --user --upgrade pipx.

Using pipx without installing (via zipapp)

You can also use pipx without installing it. The zipapp can be downloaded from Github releases and you can invoke it with a Python 3.8+ interpreter:

python pipx.pyz ensurepath

Use with pre-commit

pipx has pre-commit support.

Shell completions

Shell completions are available by following the instructions printed with this command:

pipx completions

For more details, see the installation instructions.

Overview: What is pipx?

pipx is a tool to help you install and run end-user applications written in Python. It's roughly similar to macOS's brew, JavaScript's npx, and Linux's apt.

It's closely related to pip. In fact, it uses pip, but is focused on installing and managing Python packages that can be run from the command line directly as applications.

How is it Different from pip?

pip is a general-purpose package installer for both libraries and apps with no environment isolation. pipx is made specifically for application installation, as it adds isolation yet still makes the apps available in your shell: pipx creates an isolated environment for each application and its associated packages.

pipx does not ship with pip, but installing it is often an important part of bootstrapping your system.

Where Does pipx Install Apps From?

By default, pipx uses the same package index as pip, PyPI. pipx can also install from all other sources pip can, such as a local directory, wheel, git url, etc.

Python and PyPI allow developers to distribute code with "console script entry points". These entry points let users call into Python code from the command line, effectively acting like standalone applications.

pipx is a tool to install and run any of these thousands of application-containing packages in a safe, convenient, and reliable way. In a way, it turns Python Package Index (PyPI) into a big app store for Python applications. Not all Python packages have entry points, but many do.

If you would like to make your package compatible with pipx, all you need to do is add a console scripts entry point. If you're a poetry user, use these instructions. Or, if you're using hatch, try this.

Features

pipx enables you to

  • Expose CLI entrypoints of packages ("apps") installed to isolated environments with the install command. This guarantees no dependency conflicts and clean uninstalls!
  • Easily list, upgrade, and uninstall packages that were installed with pipx
  • Run the latest version of a Python application in a temporary environment with the run command

Best of all, pipx runs with regular user permissions, never calling sudo pip install (you aren't doing that, are you? 😄).

Walkthrough: Installing a Package and its Applications With pipx

You can globally install an application by running

pipx install PACKAGE

This automatically creates a virtual environment, installs the package, and adds the package's associated applications (entry points) to a location on your PATH. For example, pipx install pycowsay makes the pycowsay command available globally, but sandboxes the pycowsay package in its own virtual environment. pipx never needs to run as sudo to do this.

Example:

>> pipx install pycowsay
  installed package pycowsay 2.0.3, Python 3.10.3
  These apps are now globally available
    - pycowsay
done! ✨ 🌟 ✨


>> pipx list
venvs are in /home/user/.local/share/pipx/venvs
apps are exposed on your $PATH at /home/user/.local/bin
   package pycowsay 2.0.3, Python 3.10.3
    - pycowsay


# Now you can run pycowsay from anywhere
>> pycowsay mooo
  ____
< mooo >
  ====
         \
          \
            ^__^
            (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

Installing from Source Control

You can also install from a git repository. Here, black is used as an example.

pipx install git+https://github.com/psf/black.git
pipx install git+https://github.com/psf/black.git@branch  # branch of your choice
pipx install git+https://github.com/psf/black.git@ce14fa8b497bae2b50ec48b3bd7022573a59cdb1  # git hash
pipx install https://github.com/psf/black/archive/18.9b0.zip  # install a release

The pip syntax with egg must be used when installing extras:

pipx install "git+https://github.com/psf/black.git#egg=black[jupyter]"

Inject a package

If an application installed by pipx requires additional packages, you can add them with pipx inject. For example, if you have ipython installed and want to add the matplotlib package to it, you would use:

pipx inject ipython matplotlib

You can inject multiple packages by specifying them all on the command line, or by listing them in a text file, with one package per line, or a combination. For example:

pipx inject ipython matplotlib pandas
# or:
pipx inject ipython -r useful-packages.txt

Walkthrough: Running an Application in a Temporary Virtual Environment

This is an alternative to pipx install.

pipx run downloads and runs the above mentioned Python "apps" in a one-time, temporary environment, leaving your system untouched afterwards.

This can be handy when you need to run the latest version of an app, but don't necessarily want it installed on your computer.

You may want to do this when you are initializing a new project and want to set up the right directory structure, when you want to view the help text of an application, or if you simply want to run an app in a one-off case and leave your system untouched afterwards.

For example, the blog post How to set up a perfect Python project uses pipx run to kickstart a new project with cookiecutter, a tool that creates projects from project templates.

A nice side benefit is that you don't have to remember to upgrade the app since pipx run will automatically run a recent version for you.

Okay, let's see what this looks like in practice!

pipx run APP [ARGS...]

This will install the package in an isolated, temporary directory and invoke the app. Give it a try:

> pipx run pycowsay moo

  ---
< moo >
  ---
   \   ^__^
    \  (oo)\_______
       (__)\       )\/\
           ||----w |
           ||     ||

Notice that you don't need to execute any install commands to run the app.

Any arguments after the application name will be passed directly to the application:

> pipx run pycowsay these arguments are all passed to pycowsay!

  -------------------------------------------
< these arguments are all passed to pycowsay! >
  -------------------------------------------
   \   ^__^
    \  (oo)\_______
       (__)\       )\/\
           ||----w |
           ||     ||

Ambiguous arguments

Sometimes pipx can consume arguments provided for the application:

> pipx run pycowsay --py

usage: pipx run [-h] [--no-cache] [--pypackages] [--spec SPEC] [--verbose] [--python PYTHON]
                [--system-site-packages] [--index-url INDEX_URL] [--editable] [--pip-args PIP_ARGS]
                app ...
pipx run: error: ambiguous option: --py could match --pypackages, --python

To prevent this put double dash -- before APP. It will make pipx to forward the arguments to the right verbatim to the application:

> pipx run -- pycowsay --py


  ----
< --py >
  ----
   \   ^__^
    \  (oo)\_______
       (__)\       )\/\
           ||----w |
           ||     ||

Re-running the same app is quick because pipx caches Virtual Environments on a per-app basis. The caches only last a few days, and when they expire, pipx will again use the latest version of the package. This way you can be sure you're always running a new version of the package without having to manually upgrade.

Package with multiple apps, or the app name doesn't match the package name

If the app name does not match the package name, you can use the --spec argument to specify the PACKAGE name, and provide the APP to run separately:

pipx run --spec PACKAGE APP

For example, the esptool package doesn't provide an executable with the same name:

>> pipx run esptool
'esptool' executable script not found in package 'esptool'.
Available executable scripts:
    esp_rfc2217_server.py - usage: 'pipx run --spec esptool esp_rfc2217_server.py [arguments?]'
    espefuse.py - usage: 'pipx run --spec esptool espefuse.py [arguments?]'
    espsecure.py - usage: 'pipx run --spec esptool espsecure.py [arguments?]'
    esptool.py - usage: 'pipx run --spec esptool esptool.py [arguments?]'

You can instead run the executables that this package provides by using --spec:

pipx run --spec esptool esp_rfc2217_server.py
pipx run --spec esptool espefuse.py
pipx run --spec esptool espsecure.py
pipx run --spec esptool esptool.py

Note that the .py extension is not something you append to the executable name. It is part of the executable name, as provided by the package. This can be anything. For example, when working with the pymodbus package:

>> pipx run pymodbus[repl]
'pymodbus' executable script not found in package 'pymodbus'.
Available executable scripts:
    pymodbus.console - usage: 'pipx run --spec pymodbus pymodbus.console [arguments?]'
    pymodbus.server - usage: 'pipx run --spec pymodbus pymodbus.server [arguments?]'
    pymodbus.simulator - usage: 'pipx run --spec pymodbus pymodbus.simulator [arguments?]'

You can run the executables like this:

pipx run --spec pymodbus[repl] pymodbus.console
pipx run --spec pymodbus[repl] pymodbus.server
pipx run --spec pymodbus[repl] pymodbus.simulator

Running a specific version of a package

The PACKAGE argument above is actually a requirement specifier. Therefore, you can also specify specific versions, version ranges, or extras. For example:

pipx run mpremote==1.20.0
pipx run --spec esptool==4.6.2 esptool.py
pipx run --spec 'esptool>=4.5' esptool.py
pipx run --spec 'esptool >= 4.5' esptool.py

Notice that some requirement specifiers have to be enclosed in quotes or escaped.

Running from Source Control

You can also run from a git repository. Here, black is used as an example.

pipx run --spec git+https://github.com/psf/black.git black
pipx run --spec git+https://github.com/psf/black.git@branch black  # branch of your choice
pipx run --spec git+https://github.com/psf/black.git@ce14fa8b497bae2b50ec48b3bd7022573a59cdb1 black  # git hash
pipx run --spec https://github.com/psf/black/archive/18.9b0.zip black # install a release

Running from URL

You can run .py files directly, too.

pipx run https://gist.githubusercontent.com/cs01/fa721a17a326e551ede048c5088f9e0f/raw/6bdfbb6e9c1132b1c38fdd2f195d4a24c540c324/pipx-demo.py
pipx is working!

Summary

That's it! Those are the most important commands pipx offers. To see all of pipx's documentation, run pipx --help or see the docs.

Testimonials

"Thanks for improving the workflow that pipsi has covered in the past. Nicely done!"
—Jannis Leidel, PSF fellow, former pip and Django core developer, and founder of the Python Packaging Authority (PyPA)

"My setup pieces together pyenv, poetry, and pipx. [...] For the things I need, it’s perfect."
—Jacob Kaplan-Moss, co-creator of Django in blog post My Python Development Environment, 2020 Edition

"I'm a big fan of pipx. I think pipx is super cool."
—Michael Kennedy, co-host of PythonBytes podcast in episode 139

Credits

pipx was inspired by pipsi and npx. It was created by Chad Smith and has had lots of help from contributors. The logo was created by @IrishMorales.

pipx is maintained by a team of volunteers (in alphabetical order)

Contributing

Issues and Pull Requests are definitely welcome! Check out Contributing to get started. Everyone who interacts with the pipx project via codebase, issue tracker, chat rooms, or otherwise is expected to follow the PSF Code of Conduct.