| Name | pipx JSON |
| Version |
1.7.1
JSON |
| download |
| home_page | None |
| Summary | Install and Run Python Applications in Isolated Environments |
| upload_time | 2024-08-23 16:53:47 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
virtual environment
cli
install
pip
workflow
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<p align="center">
<a href="https://pipx.pypa.io">
<img align="center" src="https://github.com/pypa/pipx/raw/main/logo.svg" width="200"/>
</a>
</p>
# pipx — Install and Run Python Applications in Isolated Environments
<p align="center">
<a href="https://github.com/pypa/pipx/raw/main/pipx_demo.gif">
<img src="https://github.com/pypa/pipx/raw/main/pipx_demo.gif"/>
</a>
</p>
<p align="center">
<a href="https://github.com/pypa/pipx/actions">
<img src="https://github.com/pypa/pipx/workflows/tests/badge.svg?branch=main" alt="image" /></a> <a href="https://badge.fury.io/py/pipx"><img src="https://badge.fury.io/py/pipx.svg" alt="PyPI version"></a> <a href="https://badge.fury.io/py/pipx"><img src="https://static.pepy.tech/badge/pipx"></a>
</p>
**Documentation**: <https://pipx.pypa.io>
**Source Code**: <https://github.com/pypa/pipx>
_For comparison to other tools including pipsi, see
[Comparison to Other Tools](https://pipx.pypa.io/stable/comparisons/)._
## 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`](https://github.com/mattsb42-meta/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
- install via [Scoop](https://scoop.sh/)
```
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](https://github.com/pypa/pipx/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](installation.md#pre-commit).
### Shell completions
Shell completions are available by following the instructions printed with this command:
```
pipx completions
```
For more details, see the [installation instructions](https://pipx.pypa.io/stable/installation/).
## 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](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b), 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](https://pypi.org/). 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](https://python-packaging.readthedocs.io/en/latest/command-line-scripts.html#the-console-scripts-entry-point)
entry point. If you're a poetry user, use [these instructions](https://python-poetry.org/docs/pyproject/#scripts). Or,
if you're using hatch, [try this](https://hatch.pypa.io/latest/config/metadata/#cli).
## 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](https://sourcery.ai/blog/python-best-practices/)
uses `pipx run` to kickstart a new project with [cookiecutter](https://github.com/cookiecutter/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](https://github.com/espressif/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](https://github.com/pymodbus-dev/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](https://packaging.python.org/en/latest/glossary/#term-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](https://pipx.pypa.io/stable/docs/).
## Testimonials
<div>
"Thanks for improving the workflow that pipsi has covered in the past. Nicely done!"
<div style="text-align: right; margin-right: 10%; font-style:italic;">
—<a href="https://twitter.com/jezdez">Jannis Leidel</a>, PSF fellow, former pip and Django core developer, and founder of the Python Packaging Authority (PyPA)
</div>
</div>
<p></p>
<div>
"My setup pieces together pyenv, poetry, and pipx. [...] For the things I need, it’s perfect."
<div style="text-align: right; margin-right: 10%; font-style:italic;">
—<a href="https://twitter.com/jacobian">Jacob Kaplan-Moss</a>, co-creator of Django in blog post <a href="https://jacobian.org/2019/nov/11/python-environment-2020/">My Python Development Environment, 2020 Edition</a>
</div>
</div>
<p></p>
<div>
"I'm a big fan of pipx. I think pipx is super cool."
<div style="text-align: right; margin-right: 10%; font-style:italic;">
—<a href="https://twitter.com/mkennedy">Michael Kennedy</a>, co-host of PythonBytes podcast in <a href="https://pythonbytes.fm/episodes/transcript/139/f-yes-for-the-f-strings">episode 139</a>
</div>
</div>
<p></p>
## Credits
pipx was inspired by [pipsi](https://github.com/mitsuhiko/pipsi) and [npx](https://github.com/npm/npx). It was created
by [Chad Smith](https://github.com/cs01/) and has had lots of help from
[contributors](https://github.com/pypa/pipx/graphs/contributors). The logo was created by
[@IrishMorales](https://github.com/IrishMorales).
pipx is maintained by a team of volunteers (in alphabetical order)
- [Bernát Gábor](https://github.com/gaborbernat)
- [Chad Smith](https://github.com/cs01) - co-lead maintainer
- [Chrysle](https://github.com/chrysle)
- [Jason Lam](https://github.com/dukecat0)
- [Matthew Clapp](https://github.com/itsayellow) - co-lead maintainer
- [Robert Offner](https://github.com/gitznik)
- [Tzu-ping Chung](https://github.com/uranusjr)
## Contributing
Issues and Pull Requests are definitely welcome! Check out [Contributing](https://pipx.pypa.io/stable/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](https://github.com/pypa/.github/blob/main/CODE_OF_CONDUCT.md).
Raw data
{
"_id": null,
"home_page": null,
"name": "pipx",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "Virtual Environment, cli, install, pip, workflow",
"author": null,
"author_email": "Chad Smith <chadsmith.software@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/17/21/dd6b9a9c4f0cb659ce3dad991f0e8dde852b2c81922224ef77df4222ab7a/pipx-1.7.1.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n<a href=\"https://pipx.pypa.io\">\n<img align=\"center\" src=\"https://github.com/pypa/pipx/raw/main/logo.svg\" width=\"200\"/>\n</a>\n</p>\n\n# pipx \u2014 Install and Run Python Applications in Isolated Environments\n\n<p align=\"center\">\n<a href=\"https://github.com/pypa/pipx/raw/main/pipx_demo.gif\">\n<img src=\"https://github.com/pypa/pipx/raw/main/pipx_demo.gif\"/>\n</a>\n</p>\n\n<p align=\"center\">\n<a href=\"https://github.com/pypa/pipx/actions\">\n<img src=\"https://github.com/pypa/pipx/workflows/tests/badge.svg?branch=main\" alt=\"image\" /></a> <a href=\"https://badge.fury.io/py/pipx\"><img src=\"https://badge.fury.io/py/pipx.svg\" alt=\"PyPI version\"></a> <a href=\"https://badge.fury.io/py/pipx\"><img src=\"https://static.pepy.tech/badge/pipx\"></a>\n\n</p>\n\n**Documentation**: <https://pipx.pypa.io>\n\n**Source Code**: <https://github.com/pypa/pipx>\n\n_For comparison to other tools including pipsi, see\n[Comparison to Other Tools](https://pipx.pypa.io/stable/comparisons/)._\n\n## Install pipx\n\n> [!WARNING]\n>\n> It is not recommended to install `pipx` via `pipx`. If you'd like to do this anyway, take a look at the\n> [`pipx-in-pipx`](https://github.com/mattsb42-meta/pipx-in-pipx) project and read about the limitations there.\n\n### On macOS\n\n```\nbrew install pipx\npipx ensurepath\nsudo pipx ensurepath --global # optional to allow pipx actions with --global argument\n```\n\nUpgrade pipx with `brew update && brew upgrade pipx`.\n\n### On Linux\n\n- Ubuntu 23.04 or above\n\n```\nsudo apt update\nsudo apt install pipx\npipx ensurepath\nsudo pipx ensurepath --global # optional to allow pipx actions with --global argument\n```\n\n- Fedora:\n\n```\nsudo dnf install pipx\npipx ensurepath\nsudo pipx ensurepath --global # optional to allow pipx actions with --global argument\n```\n\n- Arch:\n\n```\nsudo pacman -S python-pipx\npipx ensurepath\nsudo pipx ensurepath --global # optional to allow pipx actions with --global argument\n```\n\n- Using `pip` on other distributions:\n\n```\npython3 -m pip install --user pipx\npython3 -m pipx ensurepath\nsudo pipx ensurepath --global # optional to allow pipx actions with --global argument\n```\n\nUpgrade pipx with `python3 -m pip install --user --upgrade pipx`.\n\n### On Windows\n\n- install via [Scoop](https://scoop.sh/)\n\n```\nscoop install pipx\npipx ensurepath\n```\n\nUpgrade pipx with `scoop update pipx`.\n\n- install via pip (requires pip 19.0 or later)\n\n```\n# If you installed python using Microsoft Store, replace `py` with `python3` in the next line.\npy -m pip install --user pipx\n```\n\nIt is possible (even most likely) the above finishes with a WARNING looking similar to this:\n\n```\nWARNING: The script pipx.exe is installed in `<USER folder>\\AppData\\Roaming\\Python\\Python3x\\Scripts` which is not on PATH\n```\n\nIf so, go to the mentioned folder, allowing you to run the pipx executable directly. Enter the following line (even if\nyou did not get the warning):\n\n```\n.\\pipx.exe ensurepath\n```\n\nThis will add both the above mentioned path and the `%USERPROFILE%\\.local\\bin` folder to your search path. Restart your\nterminal session and verify `pipx` does run.\n\nUpgrade pipx with `py -m pip install --user --upgrade pipx`.\n\n### Using pipx without installing (via zipapp)\n\nYou can also use pipx without installing it. The zipapp can be downloaded from\n[Github releases](https://github.com/pypa/pipx/releases) and you can invoke it with a Python 3.8+ interpreter:\n\n```\npython pipx.pyz ensurepath\n```\n\n### Use with pre-commit\n\npipx [has pre-commit support](installation.md#pre-commit).\n\n### Shell completions\n\nShell completions are available by following the instructions printed with this command:\n\n```\npipx completions\n```\n\nFor more details, see the [installation instructions](https://pipx.pypa.io/stable/installation/).\n\n## Overview: What is `pipx`?\n\npipx is a tool to help you install and run end-user applications written in Python. It's roughly similar to macOS's\n`brew`, JavaScript's [npx](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b), and\nLinux's `apt`.\n\nIt's closely related to pip. In fact, it uses pip, but is focused on installing and managing Python packages that can be\nrun from the command line directly as applications.\n\n### How is it Different from pip?\n\npip is a general-purpose package installer for both libraries and apps with no environment isolation. pipx is made\nspecifically for application installation, as it adds isolation yet still makes the apps available in your shell: pipx\ncreates an isolated environment for each application and its associated packages.\n\npipx does not ship with pip, but installing it is often an important part of bootstrapping your system.\n\n### Where Does `pipx` Install Apps From?\n\nBy default, pipx uses the same package index as pip, [PyPI](https://pypi.org/). pipx can also install from all other\nsources pip can, such as a local directory, wheel, git url, etc.\n\nPython and PyPI allow developers to distribute code with \"console script entry points\". These entry points let users\ncall into Python code from the command line, effectively acting like standalone applications.\n\npipx is a tool to install and run any of these thousands of application-containing packages in a safe, convenient, and\nreliable way. **In a way, it turns Python Package Index (PyPI) into a big app store for Python applications.** Not all\nPython packages have entry points, but many do.\n\nIf you would like to make your package compatible with pipx, all you need to do is add a\n[console scripts](https://python-packaging.readthedocs.io/en/latest/command-line-scripts.html#the-console-scripts-entry-point)\nentry point. If you're a poetry user, use [these instructions](https://python-poetry.org/docs/pyproject/#scripts). Or,\nif you're using hatch, [try this](https://hatch.pypa.io/latest/config/metadata/#cli).\n\n## Features\n\n`pipx` enables you to\n\n- Expose CLI entrypoints of packages (\"apps\") installed to isolated environments with the `install` command. This\n guarantees no dependency conflicts and clean uninstalls!\n- Easily list, upgrade, and uninstall packages that were installed with pipx\n- Run the latest version of a Python application in a temporary environment with the `run` command\n\nBest of all, pipx runs with regular user permissions, never calling `sudo pip install` (you aren't doing that, are you?\n\ud83d\ude04).\n\n### Walkthrough: Installing a Package and its Applications With `pipx`\n\nYou can globally install an application by running\n\n```\npipx install PACKAGE\n```\n\nThis automatically creates a virtual environment, installs the package, and adds the package's associated applications\n(entry points) to a location on your `PATH`. For example, `pipx install pycowsay` makes the `pycowsay` command available\nglobally, but sandboxes the pycowsay package in its own virtual environment. **pipx never needs to run as sudo to do\nthis.**\n\nExample:\n\n```\n>> pipx install pycowsay\n installed package pycowsay 2.0.3, Python 3.10.3\n These apps are now globally available\n - pycowsay\ndone! \u2728 \ud83c\udf1f \u2728\n\n\n>> pipx list\nvenvs are in /home/user/.local/share/pipx/venvs\napps are exposed on your $PATH at /home/user/.local/bin\n package pycowsay 2.0.3, Python 3.10.3\n - pycowsay\n\n\n# Now you can run pycowsay from anywhere\n>> pycowsay mooo\n ____\n< mooo >\n ====\n \\\n \\\n ^__^\n (oo)\\_______\n (__)\\ )\\/\\\n ||----w |\n || ||\n\n```\n\n### Installing from Source Control\n\nYou can also install from a git repository. Here, `black` is used as an example.\n\n```\npipx install git+https://github.com/psf/black.git\npipx install git+https://github.com/psf/black.git@branch # branch of your choice\npipx install git+https://github.com/psf/black.git@ce14fa8b497bae2b50ec48b3bd7022573a59cdb1 # git hash\npipx install https://github.com/psf/black/archive/18.9b0.zip # install a release\n```\n\nThe pip syntax with `egg` must be used when installing extras:\n\n```\npipx install \"git+https://github.com/psf/black.git#egg=black[jupyter]\"\n```\n\n### Inject a package\n\nIf 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:\n\n```\npipx inject ipython matplotlib\n```\n\nYou can inject multiple packages by specifying them all on the command line,\nor by listing them in a text file, with one package per line,\nor a combination. For example:\n\n```\npipx inject ipython matplotlib pandas\n# or:\npipx inject ipython -r useful-packages.txt\n```\n\n### Walkthrough: Running an Application in a Temporary Virtual Environment\n\nThis is an alternative to `pipx install`.\n\n`pipx run` downloads and runs the above mentioned Python \"apps\" in a one-time, temporary environment, leaving your\nsystem untouched afterwards.\n\nThis can be handy when you need to run the latest version of an app, but don't necessarily want it installed on your\ncomputer.\n\nYou may want to do this when you are initializing a new project and want to set up the right directory structure, when\nyou 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\nsystem untouched afterwards.\n\nFor example, the blog post [How to set up a perfect Python project](https://sourcery.ai/blog/python-best-practices/)\nuses `pipx run` to kickstart a new project with [cookiecutter](https://github.com/cookiecutter/cookiecutter), a tool\nthat creates projects from project templates.\n\nA nice side benefit is that you don't have to remember to upgrade the app since `pipx run` will automatically run a\nrecent version for you.\n\nOkay, let's see what this looks like in practice!\n\n```\npipx run APP [ARGS...]\n```\n\nThis will install the package in an isolated, temporary directory and invoke the app. Give it a try:\n\n```\n> pipx run pycowsay moo\n\n ---\n< moo >\n ---\n \\ ^__^\n \\ (oo)\\_______\n (__)\\ )\\/\\\n ||----w |\n || ||\n\n\n```\n\nNotice that you **don't need to execute any install commands to run the app**.\n\nAny arguments after the application name will be passed directly to the application:\n\n```\n> pipx run pycowsay these arguments are all passed to pycowsay!\n\n -------------------------------------------\n< these arguments are all passed to pycowsay! >\n -------------------------------------------\n \\ ^__^\n \\ (oo)\\_______\n (__)\\ )\\/\\\n ||----w |\n || ||\n\n```\n\n### Ambiguous arguments\n\nSometimes pipx can consume arguments provided for the application:\n\n```\n> pipx run pycowsay --py\n\nusage: pipx run [-h] [--no-cache] [--pypackages] [--spec SPEC] [--verbose] [--python PYTHON]\n [--system-site-packages] [--index-url INDEX_URL] [--editable] [--pip-args PIP_ARGS]\n app ...\npipx run: error: ambiguous option: --py could match --pypackages, --python\n```\n\nTo prevent this put double dash `--` before APP. It will make pipx to forward the arguments to the right verbatim to the\napplication:\n\n```\n> pipx run -- pycowsay --py\n\n\n ----\n< --py >\n ----\n \\ ^__^\n \\ (oo)\\_______\n (__)\\ )\\/\\\n ||----w |\n || ||\n\n\n```\n\nRe-running the same app is quick because pipx caches Virtual Environments on a per-app basis. The caches only last a few\ndays, and when they expire, pipx will again use the latest version of the package. This way you can be sure you're\nalways running a new version of the package without having to manually upgrade.\n\n### Package with multiple apps, or the app name doesn't match the package name\n\nIf the app name does not match the package name, you can use the `--spec` argument to specify the `PACKAGE` name, and\nprovide the `APP` to run separately:\n\n```\npipx run --spec PACKAGE APP\n```\n\nFor example, the [esptool](https://github.com/espressif/esptool) package doesn't provide an executable with the same\nname:\n\n```\n>> pipx run esptool\n'esptool' executable script not found in package 'esptool'.\nAvailable executable scripts:\n esp_rfc2217_server.py - usage: 'pipx run --spec esptool esp_rfc2217_server.py [arguments?]'\n espefuse.py - usage: 'pipx run --spec esptool espefuse.py [arguments?]'\n espsecure.py - usage: 'pipx run --spec esptool espsecure.py [arguments?]'\n esptool.py - usage: 'pipx run --spec esptool esptool.py [arguments?]'\n```\n\nYou can instead run the executables that this package provides by using `--spec`:\n\n```\npipx run --spec esptool esp_rfc2217_server.py\npipx run --spec esptool espefuse.py\npipx run --spec esptool espsecure.py\npipx run --spec esptool esptool.py\n```\n\nNote that the `.py` extension is not something you append to the executable name. It is part of the executable name, as\nprovided by the package. This can be anything. For example, when working with the\n[pymodbus](https://github.com/pymodbus-dev/pymodbus) package:\n\n```\n>> pipx run pymodbus[repl]\n'pymodbus' executable script not found in package 'pymodbus'.\nAvailable executable scripts:\n pymodbus.console - usage: 'pipx run --spec pymodbus pymodbus.console [arguments?]'\n pymodbus.server - usage: 'pipx run --spec pymodbus pymodbus.server [arguments?]'\n pymodbus.simulator - usage: 'pipx run --spec pymodbus pymodbus.simulator [arguments?]'\n```\n\nYou can run the executables like this:\n\n```\npipx run --spec pymodbus[repl] pymodbus.console\npipx run --spec pymodbus[repl] pymodbus.server\npipx run --spec pymodbus[repl] pymodbus.simulator\n```\n\n### Running a specific version of a package\n\nThe `PACKAGE` argument above is actually a\n[requirement specifier](https://packaging.python.org/en/latest/glossary/#term-Requirement-Specifier). Therefore, you can\nalso specify specific versions, version ranges, or extras. For example:\n\n```\npipx run mpremote==1.20.0\npipx run --spec esptool==4.6.2 esptool.py\npipx run --spec 'esptool>=4.5' esptool.py\npipx run --spec 'esptool >= 4.5' esptool.py\n```\n\nNotice that some requirement specifiers have to be enclosed in quotes or escaped.\n\n### Running from Source Control\n\nYou can also run from a git repository. Here, `black` is used as an example.\n\n```\npipx run --spec git+https://github.com/psf/black.git black\npipx run --spec git+https://github.com/psf/black.git@branch black # branch of your choice\npipx run --spec git+https://github.com/psf/black.git@ce14fa8b497bae2b50ec48b3bd7022573a59cdb1 black # git hash\npipx run --spec https://github.com/psf/black/archive/18.9b0.zip black # install a release\n```\n\n### Running from URL\n\nYou can run .py files directly, too.\n\n```\npipx run https://gist.githubusercontent.com/cs01/fa721a17a326e551ede048c5088f9e0f/raw/6bdfbb6e9c1132b1c38fdd2f195d4a24c540c324/pipx-demo.py\npipx is working!\n```\n\n### Summary\n\nThat's it! Those are the most important commands `pipx` offers. To see all of pipx's documentation, run `pipx --help` or\nsee the [docs](https://pipx.pypa.io/stable/docs/).\n\n## Testimonials\n\n<div>\n\"Thanks for improving the workflow that pipsi has covered in the past. Nicely done!\"\n<div style=\"text-align: right; margin-right: 10%; font-style:italic;\">\n\u2014<a href=\"https://twitter.com/jezdez\">Jannis Leidel</a>, PSF fellow, former pip and Django core developer, and founder of the Python Packaging Authority (PyPA)\n</div>\n</div>\n\n<p></p>\n\n<div>\n\"My setup pieces together pyenv, poetry, and pipx. [...] For the things I need, it\u2019s perfect.\"\n<div style=\"text-align: right; margin-right: 10%; font-style:italic;\">\n\u2014<a href=\"https://twitter.com/jacobian\">Jacob Kaplan-Moss</a>, co-creator of Django in blog post <a href=\"https://jacobian.org/2019/nov/11/python-environment-2020/\">My Python Development Environment, 2020 Edition</a>\n</div>\n</div>\n\n<p></p>\n\n<div>\n\"I'm a big fan of pipx. I think pipx is super cool.\"\n<div style=\"text-align: right; margin-right: 10%; font-style:italic;\">\n\u2014<a href=\"https://twitter.com/mkennedy\">Michael Kennedy</a>, co-host of PythonBytes podcast in <a href=\"https://pythonbytes.fm/episodes/transcript/139/f-yes-for-the-f-strings\">episode 139</a>\n</div>\n</div>\n\n<p></p>\n\n## Credits\n\npipx was inspired by [pipsi](https://github.com/mitsuhiko/pipsi) and [npx](https://github.com/npm/npx). It was created\nby [Chad Smith](https://github.com/cs01/) and has had lots of help from\n[contributors](https://github.com/pypa/pipx/graphs/contributors). The logo was created by\n[@IrishMorales](https://github.com/IrishMorales).\n\npipx is maintained by a team of volunteers (in alphabetical order)\n\n- [Bern\u00e1t G\u00e1bor](https://github.com/gaborbernat)\n- [Chad Smith](https://github.com/cs01) - co-lead maintainer\n- [Chrysle](https://github.com/chrysle)\n- [Jason Lam](https://github.com/dukecat0)\n- [Matthew Clapp](https://github.com/itsayellow) - co-lead maintainer\n- [Robert Offner](https://github.com/gitznik)\n- [Tzu-ping Chung](https://github.com/uranusjr)\n\n## Contributing\n\nIssues and Pull Requests are definitely welcome! Check out [Contributing](https://pipx.pypa.io/stable/contributing/) to\nget started. Everyone who interacts with the pipx project via codebase, issue tracker, chat rooms, or otherwise is\nexpected to follow the [PSF Code of Conduct](https://github.com/pypa/.github/blob/main/CODE_OF_CONDUCT.md).\n",
"bugtrack_url": null,
"license": null,
"summary": "Install and Run Python Applications in Isolated Environments",
"version": "1.7.1",
"project_urls": {
"Bug Tracker": "https://github.com/pypa/pipx/issues",
"Documentation": "https://pipx.pypa.io",
"Homepage": "https://pipx.pypa.io",
"Release Notes": "https://pipx.pypa.io/latest/changelog/",
"Source Code": "https://github.com/pypa/pipx"
},
"split_keywords": [
"virtual environment",
" cli",
" install",
" pip",
" workflow"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "35af66db02a214590a841bcd1df1f02f7ef818dc3f43487acddab0b8c40b25d2",
"md5": "661d46043471572fff2f5a0ff3e4a805",
"sha256": "3933c43bb344e649cb28e10d357e0967ce8572f1c19caf90cf39ae95c2a0afaf"
},
"downloads": -1,
"filename": "pipx-1.7.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "661d46043471572fff2f5a0ff3e4a805",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 78749,
"upload_time": "2024-08-23T16:53:46",
"upload_time_iso_8601": "2024-08-23T16:53:46.385648Z",
"url": "https://files.pythonhosted.org/packages/35/af/66db02a214590a841bcd1df1f02f7ef818dc3f43487acddab0b8c40b25d2/pipx-1.7.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1721dd6b9a9c4f0cb659ce3dad991f0e8dde852b2c81922224ef77df4222ab7a",
"md5": "7b2bd7c1397e74e7e7beb04b121702c4",
"sha256": "762de134e16a462be92645166d225ecef446afaef534917f5f70008d63584360"
},
"downloads": -1,
"filename": "pipx-1.7.1.tar.gz",
"has_sig": false,
"md5_digest": "7b2bd7c1397e74e7e7beb04b121702c4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 291889,
"upload_time": "2024-08-23T16:53:47",
"upload_time_iso_8601": "2024-08-23T16:53:47.987702Z",
"url": "https://files.pythonhosted.org/packages/17/21/dd6b9a9c4f0cb659ce3dad991f0e8dde852b2c81922224ef77df4222ab7a/pipx-1.7.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-23 16:53:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pypa",
"github_project": "pipx",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pipx"
}
