Repository files navigation

Documentation:https://pipx.pypa.io

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

For comparison to other tools including pipsi, seeComparison to Other Tools.

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

Upgrade pipx withbrew update && brew upgrade pipx.

• Ubuntu 23.04 or above

sudo apt updatesudo apt install pipxpipx ensurepathsudo pipx ensurepath --global # optional to allow pipx actions with --global argument

• Fedora:

sudo dnf install pipxpipx ensurepathsudo pipx ensurepath --global # optional to allow pipx actions with --global argument

• Arch:

sudo pacman -S python-pipxpipx ensurepathsudo pipx ensurepath --global # optional to allow pipx actions with --global argument

• Usingpip on other distributions:

python3 -m pip install --user pipxpython3 -m pipx ensurepathsudo pipx ensurepath --global # optional to allow pipx actions with --global argument

Upgrade pipx withpython3 -m pip install --user --upgrade pipx.

• install viaScoop

scoop install pipxpipx ensurepath

Upgrade pipx withscoop 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 ifyou 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 yourterminal session and verifypipx does run.

Upgrade pipx withpy -m pip install --user --upgrade pipx.

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

python pipx.pyz ensurepath

pipxhas pre-commit support.

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

pipx completions

For more details, see theinstallation instructions.

pipx is a tool to help you install and run end-user applications written in Python. It's roughly similar to macOS'sbrew, JavaScript'snpx, andLinux'sapt.

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

pip is a general-purpose package installer for both libraries and apps with no environment isolation. pipx is madespecifically for application installation, as it adds isolation yet still makes the apps available in your shell: pipxcreates 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.

By default, pipx uses the same package index as pip,PyPI. pipx can also install from all othersources 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 userscall 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, andreliable way.In a way, it turns Python Package Index (PyPI) into a big app store for Python applications. Not allPython 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 aconsole scriptsentry point. If you're a poetry user, usethese instructions. Or,if you're using hatch,try this.

pipx enables you to

• Expose CLI entrypoints of packages ("apps") installed to isolated environments with theinstall command. Thisguarantees 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 therun command

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

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 yourPATH. For example,pipx install pycowsay makes thepycowsay command availableglobally, but sandboxes the pycowsay package in its own virtual environment.pipx never needs to run as sudo to dothis.

Example:

>> pipx install pycowsay  installed package pycowsay 2.0.3, Python 3.10.3  These apps are now globally available    - pycowsaydone! ✨ 🌟 ✨>> pipx listvenvs are in /home/user/.local/share/pipx/venvsapps 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 |                ||     ||

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

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

The pip syntax withegg must be used when installing extras:

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

If an application installed by pipx requires additional packages, you can add them with pipx inject. For example, if you haveipython installed and want to add thematplotlib 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

This is an alternative topipx install.

pipx run downloads and runs the above mentioned Python "apps" in a one-time, temporary environment, leaving yoursystem 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 yourcomputer.

You may want to do this when you are initializing a new project and want to set up the right directory structure, whenyou 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 yoursystem untouched afterwards.

For example, the blog postHow to set up a perfect Python projectusespipx run to kickstart a new project withcookiecutter, a toolthat creates projects from project templates.

A nice side benefit is that you don't have to remember to upgrade the app sincepipx run will automatically run arecent 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 youdon'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 |           ||     ||

Sometimes pipx can consume arguments provided for the application:

> pipx run pycowsay --pyusage: 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 theapplication:

> 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 fewdays, and when they expire, pipx will again use the latest version of the package. This way you can be sure you'realways running a new version of the package without having to manually upgrade.

If the app name does not match the package name, you can use the--spec argument to specify thePACKAGE name, andprovide theAPP to run separately:

pipx run --spec PACKAGE APP

For example, theesptool package doesn't provide an executable with the samename:

>> 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.pypipx run --spec esptool espefuse.pypipx run --spec esptool espsecure.pypipx 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, asprovided by the package. This can be anything. For example, when working with thepymodbus 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.consolepipx run --spec pymodbus[repl] pymodbus.serverpipx run --spec pymodbus[repl] pymodbus.simulator

ThePACKAGE argument above is actually arequirement specifier. Therefore, you canalso specify specific versions, version ranges, or extras. For example:

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

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

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 blackpipx run --spec git+https://github.com/psf/black.git@branch black  # branch of your choicepipx run --spec git+https://github.com/psf/black.git@ce14fa8b497bae2b50ec48b3bd7022573a59cdb1 black  # git hashpipx run --spec https://github.com/psf/black/archive/18.9b0.zip black # install a release

You can run .py files directly, too.

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

That's it! Those are the most important commandspipx offers. To see all of pipx's documentation, runpipx --help orsee thedocs.

pipx was inspired bypipsi andnpx. It was createdbyChad Smith and has had lots of help fromcontributors. The logo was created by@IrishMorales.

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

• Bernát Gábor
• Chad Smith - co-lead maintainer
• Chrysle
• Jason Lam
• Matthew Clapp - co-lead maintainer
• Robert Offner
• Tzu-ping Chung

Issues and Pull Requests are definitely welcome! Check outContributing toget started. Everyone who interacts with the pipx project via codebase, issue tracker, chat rooms, or otherwise isexpected to follow thePSF Code of Conduct.