• Stars
    star
    8,438
  • Rank 4,145 (Top 0.09 %)
  • Language
    Python
  • License
    MIT License
  • Created over 5 years ago
  • Updated 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Install and Run Python Applications in Isolated Environments

pipx โ€” Install and Run Python Applications in Isolated Environments

image PyPI version

Documentation: https://pypa.github.io/pipx/

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

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

Install pipx

On macOS

brew install pipx
pipx ensurepath

Upgrade pipx with brew update && brew upgrade pipx.

On Linux, install via pip (requires pip 19.0 or later)

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

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

On Windows, install via pip (requires pip 19.0 or later)

# If you installed python using the app-store, replace `python` with `python3` in the next line.
python -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 python3 -m pip install --user --upgrade pipx.

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.7+ 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 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.7.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.7.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]"

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.

More Repositories

1

pipenv

Python Development Workflow for Humans.
Python
24,500
star
2

pip

The Python package installer
Python
9,178
star
3

hatch

Modern, extensible Python project management
Python
5,078
star
4

sampleproject

A sample project that exists for PyPUG's "Tutorial on Packaging and Distributing Projects"
Python
4,914
star
5

virtualenv

Virtual Python Environment builder
Python
4,642
star
6

pipfile

Python
3,231
star
7

setuptools

Official project repository for the Setuptools build system
Python
2,251
star
8

flit

Simplified packaging of Python modules
Python
2,070
star
9

cibuildwheel

๐ŸŽก Build Python wheels for all the platforms with minimal configuration.
Python
1,684
star
10

twine

Utilities for interacting with PyPI
Python
1,543
star
11

manylinux

Python wheels that work on any linux (almost)
Shell
1,365
star
12

packaging.python.org

Python Packaging User Guide
Python
1,362
star
13

pip-audit

Audits Python environments and dependency trees for known vulnerabilities
Python
888
star
14

setuptools_scm

the blessed package to manage your versions by scm tags
Python
802
star
15

gh-action-pypi-publish

The blessed :octocat: GitHub Action, for publishing your ๐Ÿ“ฆ distribution files to PyPI: https://github.com/marketplace/actions/pypi-publish
Python
795
star
16

get-pip

Helper scripts to install pip, in a Python installation that doesn't have it.
Python
694
star
17

build

A simple, correct Python build frontend
Python
667
star
18

packaging

Core utilities for Python packages
Python
566
star
19

wheel

The official binary distribution format for Python
Python
469
star
20

bandersnatch

A PyPI mirror client according to PEP 381 http://www.python.org/dev/peps/pep-0381/
Python
421
star
21

auditwheel

Auditing and relabeling cross-distribution Linux wheels.
Python
403
star
22

advisory-database

Advisory database for Python packages published on pypi.org
236
star
23

python-manylinux-demo

Demo project for building Python wheels for Linux with Travis-CI
C
221
star
24

sample-namespace-packages

Tests against namespace packages
Python
166
star
25

readme_renderer

Safely render long_description/README files in Warehouse
Python
151
star
26

packaging-problems

An issue tracker for the problems in packaging
140
star
27

trove-classifiers

Canonical source for classifiers on PyPI.
Python
126
star
28

pyproject-hooks

A low-level library for calling build-backends in `pyproject.toml`-based project
Python
115
star
29

installer

A low-level library for installing from a Python wheel distribution.
Python
107
star
30

scripttest

Utilities to help with testing command line scripts
Python
59
star
31

gh-action-pip-audit

A GitHub Action for pip-audit
Python
59
star
32

distlib

A low-level library which implements some Python packaging standards (PEPs) and which could be used by third-party packaging tools to achieve interoperability.
Python
43
star
33

distutils

distutils as found in cpython
Python
42
star
34

.github

Community health files for the Python Packaging Authority
30
star
35

interoperability-peps

Development repo for evolution of PyPA interoperability standards (released versions are published as PEPs on python.org)
Python
22
star
36

pypa.io

Source code for the pypa.io website
Python
22
star
37

integration-test

ensure core packaging tools work well with each other
17
star
38

pkg_resources

Abandoned extraction of pkg_resources. Official version found at /pypa/setuptools.
Python
15
star
39

get-virtualenv

14
star
40

history

history generates history/changelog files for a project
Python
7
star
41

easy_install

Python
7
star
42

wheel-builders

Companion repo for the [email protected] mailing list
7
star
43

browntruck

Python
6
star
44

pypa-docs-theme

Common base Sphinx theme for PyPA projects
Python
6
star
45

docker-python

5
star
46

copr

Package files for building PyPA packages in copr
4
star
47

pep470

Python
4
star
48

pip-test-package

Used in pip's test suite
Python
4
star
49

pypa-bot

Source code behind @pypa-bot (eventually)
3
star
50

pypi-camo

Dockerfile
3
star
51

bot-test

1
star