pax_global_header 0000666 0000000 0000000 00000000064 15210205776 0014517 g ustar 00root root 0000000 0000000 52 comment=7424ad41c71a3c41aa275afd6214186e5fd56377
pipx-1.14.0/ 0000775 0000000 0000000 00000000000 15210205776 0012562 5 ustar 00root root 0000000 0000000 pipx-1.14.0/.deepsource.toml 0000664 0000000 0000000 00000000270 15210205776 0015672 0 ustar 00root root 0000000 0000000 version = 1
test_patterns = ["tests/**"]
[[analyzers]]
name = "python"
enabled = true
[analyzers.meta]
runtime_version = "3.x.x"
[[transformers]]
name = "black"
enabled = true
pipx-1.14.0/.github/ 0000775 0000000 0000000 00000000000 15210205776 0014122 5 ustar 00root root 0000000 0000000 pipx-1.14.0/.github/CONTRIBUTING.md 0000664 0000000 0000000 00000001005 15210205776 0016347 0 ustar 00root root 0000000 0000000 # Contributing to `pipx`
Thank you for your interest in contributing to pipx! There are many ways to contribute, and we appreciate all of them.
As a reminder, all contributors are expected to follow the [PSF Code of Conduct][coc].
## Development Documentation
Our [development documentation](https://pipx.pypa.io/latest/contributing/) contains details on how to get started with
contributing to `pipx`, and details of our development processes.
[coc]: https://github.com/pypa/.github/blob/main/CODE_OF_CONDUCT.md
pipx-1.14.0/.github/FUNDING.yaml 0000664 0000000 0000000 00000000026 15210205776 0016076 0 ustar 00root root 0000000 0000000 tidelift: "pypi/pipx"
pipx-1.14.0/.github/ISSUE_TEMPLATE/ 0000775 0000000 0000000 00000000000 15210205776 0016305 5 ustar 00root root 0000000 0000000 pipx-1.14.0/.github/ISSUE_TEMPLATE/bug.md 0000664 0000000 0000000 00000000561 15210205776 0017406 0 ustar 00root root 0000000 0000000 ---
name: Bug report
about: Create a report to help us improve
title: ''
labels: bug
assignees: ''
---
**Issue**
Describe what's the expected behavior and what you're observing.
**Environment**
Provide at least:
- OS:
- Shell:
- Python version and path:
- `pipx --version` output:
**Output of the failing command**
Make sure to run the command with `--verbose`:
pipx-1.14.0/.github/ISSUE_TEMPLATE/config.yml 0000664 0000000 0000000 00000001261 15210205776 0020275 0 ustar 00root root 0000000 0000000 # Ref: https://help.github.com/en/github/building-a-strong-community/configuring-issue-templates-for-your-repository#configuring-the-template-chooser
blank_issues_enabled: true # default
contact_links:
- name: "๐ฌ pypa/pipx @ Discord"
url: https://discord.gg/pypa
about: Chat with the devs
- name: ๐คท๐ป๐คฆ Discourse
url: https://discuss.python.org/c/packaging
about: |
Please ask typical Q&A here: general ideas for Python packaging, questions about structuring projects and so on
- name: ๐ PSF Code of Conduct
url: https://github.com/pypa/.github/blob/main/CODE_OF_CONDUCT.md
about: โค Be nice to other members of the community. โฎ Behave.
pipx-1.14.0/.github/ISSUE_TEMPLATE/feature_request.md 0000664 0000000 0000000 00000001350 15210205776 0022031 0 ustar 00root root 0000000 0000000 ---
name: Feature request
about: Suggest an enhancement for this project
title: ''
labels: enhancement
assignees: ''
---
**What's the problem this feature will solve?**
**Describe the solution you'd like**
**Alternative Solutions**
**Additional context**
pipx-1.14.0/.github/PULL_REQUEST_TEMPLATE.md 0000664 0000000 0000000 00000000756 15210205776 0017733 0 ustar 00root root 0000000 0000000 ### Thanks for contributing, make sure you address all the checklists (for details on how see [development documentation](https://pipx.pypa.io/latest/contributing/))
- [ ] ran the linter to address style issues (`pre-commit run --all-files`)
- [ ] wrote descriptive pull request text
- [ ] ensured there are test(s) validating the fix
- [ ] added news fragment in `changelog.d/` folder (choose a type: `feature`, `bugfix`, `doc`, `removal`, or `misc`)
- [ ] updated/extended the documentation
pipx-1.14.0/.github/SECURITY.md 0000664 0000000 0000000 00000000555 15210205776 0015720 0 ustar 00root root 0000000 0000000 # Security Policy
## Supported Versions
| Version | Supported |
| ------- | ------------------ |
| 1.7.0+ | :white_check_mark: |
| < 1.7.0 | :x: |
## Reporting a Vulnerability
To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security). Tidelift
will coordinate the fix and disclosure.
pipx-1.14.0/.github/config.yml 0000664 0000000 0000000 00000000025 15210205776 0016107 0 ustar 00root root 0000000 0000000 rtd:
project: pipx
pipx-1.14.0/.github/dependabot.yaml 0000664 0000000 0000000 00000000323 15210205776 0017111 0 ustar 00root root 0000000 0000000 version: 2
updates:
- package-ecosystem: github-actions
directory: "/"
schedule:
interval: weekly
groups:
actions:
patterns:
- "*"
cooldown:
default-days: 7
pipx-1.14.0/.github/release.yml 0000664 0000000 0000000 00000000162 15210205776 0016264 0 ustar 00root root 0000000 0000000 changelog:
exclude:
authors:
- dependabot[bot]
- pre-commit-ci[bot]
- github-actions[bot]
pipx-1.14.0/.github/workflows/ 0000775 0000000 0000000 00000000000 15210205776 0016157 5 ustar 00root root 0000000 0000000 pipx-1.14.0/.github/workflows/create_tests_package_lists.yml 0000664 0000000 0000000 00000002543 15210205776 0024264 0 ustar 00root root 0000000 0000000 name: Create tests package lists for offline tests
on:
workflow_dispatch:
concurrency:
group: create-tests-package-lists-${{ github.ref }}
cancel-in-progress: true
permissions:
contents: read
jobs:
create_package_lists:
name: Create package lists
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest]
python-version: ["3.13", "3.12", "3.11", "3.10"]
include:
- os: macos-latest
python-version: "3.13"
- os: windows-latest
python-version: "3.13"
steps:
- uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
with:
persist-credentials: false
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
with:
python-version: ${{ matrix.python-version }}
cache: "pip"
- name: Install nox
run: python -m pip install nox
- name: Create lists
run: nox --non-interactive --session create_test_package_list-${{ matrix.python-version }} -- ./new_tests_packages
- name: Store reports as artifacts
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
with:
name: lists-${{ matrix.os }}-${{ matrix.python-version }}
path: ./new_tests_packages
pipx-1.14.0/.github/workflows/exhaustive_package_test.yml 0000664 0000000 0000000 00000005070 15210205776 0023603 0 ustar 00root root 0000000 0000000 name: Exhaustive Package Test (slow)
on:
workflow_dispatch:
concurrency:
group: exhaustive-package-test-${{ github.ref }}
cancel-in-progress: true
permissions:
contents: read
jobs:
test_all_packages:
name: Exhaustive Package Test
continue-on-error: true
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
python-version: ["3.12", "3.11", "3.10"]
steps:
- uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
with:
persist-credentials: false
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
with:
python-version: ${{ matrix.python-version }}
cache: "pip"
- name: Install nox
run: python -m pip install nox
- name: Execute Tests
continue-on-error: true
run: nox --non-interactive --session test_all_packages-${{ matrix.python-version }}
- name: Store reports as artifacts
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
with:
name: reports-raw-${{ matrix.os }}-${{ matrix.python-version }}
path: reports
report_all_packages:
name: Collate test reports
needs: test_all_packages
runs-on: ubuntu-latest
steps:
- name: Get report artifacts
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
with:
pattern: reports-raw-*
merge-multiple: true
- name: Collate reports
run: |
ls # DEBUG
mkdir reports
cat all_packages_report_legend.txt > all_nodeps_reports_lf.txt
cat all_packages_nodeps_report_* >> all_nodeps_reports_lf.txt
tr -d '\r' < all_nodeps_reports_lf.txt > reports/all_nodeps_reports.txt
cat all_packages_nodeps_errors_* > all_nodeps_errors_lf.txt
tr -d '\r' < all_nodeps_errors_lf.txt > reports/all_nodeps_errors.txt
cat all_packages_report_legend.txt > all_deps_reports_lf.txt
cat all_packages_deps_report_* >> all_deps_reports_lf.txt
tr -d '\r' < all_deps_reports_lf.txt > reports/all_deps_reports.txt
cat all_packages_deps_errors_* > all_deps_errors_lf.txt
tr -d '\r' < all_deps_errors_lf.txt > reports/all_deps_errors.txt
- name: Store collated and raw reports as artifacts
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
with:
name: reports-final
path: reports
pipx-1.14.0/.github/workflows/pre-release.yml 0000664 0000000 0000000 00000002565 15210205776 0021116 0 ustar 00root root 0000000 0000000 name: Pre-release
on:
workflow_dispatch:
inputs:
bump:
description: "Version bump type"
required: true
type: choice
options:
- auto
- major
- minor
- patch
default: auto
env:
default-python: "3.13"
jobs:
pre-release:
runs-on: ubuntu-latest
environment: release
permissions:
contents: write
steps:
- name: Checkout code
uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
with:
fetch-depth: 0
token: ${{ secrets.GH_RELEASE_TOKEN }}
persist-credentials: false
- name: Set up Python ${{ env.default-python }}
uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
with:
python-version: ${{ env.default-python }}
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install GitPython packaging towncrier pre-commit
- name: Configure git identity
run: |
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
- name: Generate changelog, commit, tag, and push
run: python scripts/release.py --version "${{ inputs.bump }}"
env:
GH_RELEASE_TOKEN: ${{ secrets.GH_RELEASE_TOKEN }}
pipx-1.14.0/.github/workflows/release.yml 0000664 0000000 0000000 00000005464 15210205776 0020333 0 ustar 00root root 0000000 0000000 name: Release
on:
push:
tags:
- "*.*.*"
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
env:
default-python: "3.14"
jobs:
build-package:
name: Build pipx package
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- name: Checkout ${{ github.ref_name }}
uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
with:
ref: "${{ github.ref_name }}"
persist-credentials: false
- name: Set up Python ${{ env.default-python }}
uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
with:
python-version: ${{ env.default-python }}
- name: Build sdist and wheel
run: |
pip install build
python -m build
- name: Upload distributions
uses: actions/upload-artifact@v7
with:
name: dist
path: dist/
pypi-publish:
name: Publish pipx to PyPI
needs: build-package
runs-on: ubuntu-latest
environment:
name: release
url: https://pypi.org/p/pipx
permissions:
id-token: write
steps:
- name: Download distributions
uses: actions/download-artifact@v8
with:
name: dist
path: dist/
- name: Publish to PyPI
uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
create-release:
name: Create a release on GitHub's UI
needs: pypi-publish
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
with:
persist-credentials: false
- name: Create release
run: |
gh release create --repo pypa/pipx "${RELEASE_TAG}" --generate-notes
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
RELEASE_TAG: ${{ github.ref_name }}
upload-zipapp:
name: Upload zipapp to GitHub Release
needs: create-release
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- name: Checkout ${{ github.ref_name }}
uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
with:
ref: "${{ github.ref_name }}"
persist-credentials: false
- name: Set up Python ${{ env.default-python }}
uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
with:
python-version: ${{ env.default-python }}
- name: Install tox
run: pip install tox
- name: Build zipapp
run: tox run -e zipapp
- name: Upload to release
run: |
gh release upload --repo pypa/pipx "${RELEASE_TAG}" pipx.pyz
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
RELEASE_TAG: ${{ github.ref_name }}
pipx-1.14.0/.github/workflows/tests.yml 0000664 0000000 0000000 00000006551 15210205776 0020053 0 ustar 00root root 0000000 0000000 name: ๐งช tests
on:
workflow_dispatch:
push:
branches:
- "main"
pull_request:
schedule:
- cron: "0 8 * * *"
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
permissions:
contents: read
jobs:
test:
name: ๐งช test ${{ matrix.py }} - ${{ matrix.os }}
runs-on: ${{ matrix.os }}
timeout-minutes: 40
strategy:
fail-fast: false
matrix:
os: [ubuntu-24.04]
py: ["3.13", "3.12", "3.11", "3.10"]
include:
- os: windows-2025
py: "3.13"
- os: macos-15
py: "3.13"
steps:
- name: ๐ฅ Checkout code
uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
with:
fetch-depth: 0
persist-credentials: false
- name: ๐ Install uv
uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
- name: ๐ Setup Python ${{ matrix.py }}
uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
with:
python-version: ${{ matrix.py }}
- name: ๐ฆ Install tox
run: uv tool install --python-preference only-managed --python 3.13 "tox>=4.45" --with tox-uv
- name: Persistent .pipx_tests/package_cache
uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5
with:
path: ${{ github.workspace }}/.pipx_tests/package_cache/${{ matrix.py }}
key: pipx-tests-package-cache-${{ runner.os }}-${{ matrix.py }}
- name: ๐๏ธ Setup test suite
run: tox run -vv --notest --skip-missing-interpreters false -e ${{ matrix.py }}
- name: ๐ฆ Seed package cache
run: tox exec -e ${{ matrix.py }} -- python scripts/update_package_cache.py testdata/tests_packages .pipx_tests/package_cache/
- name: ๐ Run test suite
run: tox run --skip-pkg-install -e ${{ matrix.py }}
timeout-minutes: 30
env:
PYTEST_ADDOPTS: "-vv --durations=20"
man:
name: ๐ Build man page
runs-on: ubuntu-24.04
steps:
- name: ๐ฅ Checkout code
uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
with:
persist-credentials: false
- name: ๐ Install uv
uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
- name: ๐ฆ Install tox
run: uv tool install --python-preference only-managed --python 3.13 "tox>=4.45" --with tox-uv
- name: ๐ Build man page
run: tox run -e man
- name: Show man page
run: man -l pipx.1
zipapp:
name: ๐ฆ Build zipapp
runs-on: ubuntu-24.04
steps:
- name: ๐ฅ Checkout code
uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
with:
persist-credentials: false
- name: ๐ Setup Python 3.10
uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
with:
python-version: "3.10"
- name: ๐ฆ Build zipapp
run: |
pip install shiv
shiv -c pipx -o ./pipx.pyz .
./pipx.pyz --version
- name: Test zipapp by installing black
run: python ./pipx.pyz install black
- uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
with:
name: pipx.pyz
path: pipx.pyz
retention-days: 3
pipx-1.14.0/.github/workflows/zizmor.yml 0000664 0000000 0000000 00000001166 15210205776 0020240 0 ustar 00root root 0000000 0000000 name: GitHub Actions Security Analysis with zizmor ๐
on:
push:
branches: ["main"]
pull_request:
branches: ["**"]
permissions: {}
jobs:
zizmor:
name: Run zizmor ๐
runs-on: ubuntu-latest
permissions:
security-events: write # Required for upload-sarif (used by zizmor-action) to upload SARIF files.
steps:
- name: Checkout repository
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
persist-credentials: false
- name: Run zizmor ๐
uses: zizmorcore/zizmor-action@5f14fd08f7cf1cb1609c1e344975f152c7ee938d # v0.5.6
pipx-1.14.0/.gitignore 0000664 0000000 0000000 00000000324 15210205776 0014551 0 ustar 00root root 0000000 0000000 /.*_cache
/build
/dist
/src/pipx/version.py
/noxfile.py
/.nox
*.py[co]
__pycache__
/site
/.coverage*
/.pipx_tests
/testdata/tests_packages/*.txt
/pipx.pyz
*.egg-info
build
*.whl
/pipx.1
/docs/_draft_changelog.md
pipx-1.14.0/.pre-commit-config.yaml 0000664 0000000 0000000 00000003411 15210205776 0017042 0 ustar 00root root 0000000 0000000 repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v6.0.0
hooks:
- id: end-of-file-fixer
- id: check-added-large-files
- id: trailing-whitespace
- id: check-merge-conflict
- id: check-case-conflict
- repo: https://github.com/google/yamlfmt
rev: v0.21.0
hooks:
- id: yamlfmt
- repo: https://github.com/hukkin/mdformat
rev: 1.0.0
hooks:
- id: mdformat
args: ["--wrap", "120"]
additional_dependencies:
- mdformat-mkdocs
- mdformat-gfm
- mdformat-gfm-alerts
- mdformat-footnote
- mdformat-config
- mdformat-front-matters
exclude: ^(docs/changelog\.md|testdata)
- repo: https://github.com/tox-dev/pyproject-fmt
rev: v2.23.0
hooks:
- id: pyproject-fmt
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.15.15
hooks:
- id: ruff-check
args: ["--fix", "--unsafe-fixes", "--show-fixes", "--exit-non-zero-on-fix"]
- id: ruff-format
- repo: https://github.com/pre-commit/mirrors-mypy
rev: v2.1.0
hooks:
- id: mypy
args: ['--warn-unused-ignores', '--strict-equality', '--no-implicit-optional', '--check-untyped-defs']
exclude: 'testdata/test_package_specifier/local_extras/setup.py'
additional_dependencies:
- "mkdocs-gen-files"
- "nox"
- "packaging>=20"
- "platformdirs>=2.1"
- "pytest"
- "pytest-mock"
- "tomli; python_version < '3.11'"
# Configuration for codespell is in pyproject.toml
- repo: https://github.com/codespell-project/codespell
rev: v2.4.2
hooks:
- id: codespell
additional_dependencies:
- tomli
exclude: ^testdata
pipx-1.14.0/.pre-commit-hooks.yaml 0000664 0000000 0000000 00000000172 15210205776 0016721 0 ustar 00root root 0000000 0000000 - id: pipx
name: pipx
entry: pipx run
require_serial: true
language: python
minimum_pre_commit_version: '2.9.2'
pipx-1.14.0/.readthedocs.yml 0000664 0000000 0000000 00000000210 15210205776 0015641 0 ustar 00root root 0000000 0000000 version: 2
build:
os: ubuntu-22.04
tools:
python: "3.13"
commands:
- pip install "tox>=4.45" tox-uv
- tox run -e docs
pipx-1.14.0/LICENSE 0000664 0000000 0000000 00000002074 15210205776 0013572 0 ustar 00root root 0000000 0000000 MIT License
Copyright (c) 2018 Chad Smith and contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
pipx-1.14.0/changelog.d/ 0000775 0000000 0000000 00000000000 15210205776 0014733 5 ustar 00root root 0000000 0000000 pipx-1.14.0/changelog.d/.gitignore 0000664 0000000 0000000 00000000014 15210205776 0016716 0 ustar 00root root 0000000 0000000 !.gitignore
pipx-1.14.0/docs/ 0000775 0000000 0000000 00000000000 15210205776 0013512 5 ustar 00root root 0000000 0000000 pipx-1.14.0/docs/README.md 0000664 0000000 0000000 00000005530 15210205776 0014774 0 ustar 00root root 0000000 0000000
# pipx โ Install and Run Python Applications in Isolated Environments
**Documentation**:
**Source Code**:
_For comparison to other tools including pipsi, see
[Comparison to Other Tools](https://pipx.pypa.io/stable/explanation/comparisons/)._
## 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.
### Features
`pipx` enables you to
- expose CLI entrypoints of packages ("apps") installed to isolated environments with the `install` command,
guaranteeing no dependency conflicts and clean uninstalls;
- easily list, upgrade, and uninstall packages that were installed with pipx; and
- 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`.
## Install pipx
### On macOS
```
brew install pipx
pipx ensurepath
```
### On Linux
```
python3 -m pip install --user pipx
python3 -m pipx ensurepath
```
### On Windows
```
scoop install pipx
pipx ensurepath
```
For more detailed installation instructions, see the
[full documentation](https://pipx.pypa.io/stable/how-to/install-pipx/).
## Quick Start
Install an application globally:
```
pipx install pycowsay
pycowsay mooo
```
Run an application without installing:
```
pipx run pycowsay moo
```
See the [full documentation](https://pipx.pypa.io/stable/) for more details.
## 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).
pipx-1.14.0/docs/changelog.md 0000664 0000000 0000000 00000135200 15210205776 0015764 0 ustar 00root root 0000000 0000000 # Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
This project uses [*towncrier*](https://towncrier.readthedocs.io/) for keeping the changelog. DO NOT commit any changes to this file.
{% include '_draft_changelog.md' ignore missing %}
## [1.14.0](https://github.com/pypa/pipx/tree/1.14.0) - 2026-06-04
### Features
- Add `--no-path-check` to `pipx run` to skip the warning when the app is already on `PATH`. Useful for shim scripts that
wrap `pipx run ` under the same name as the app. ([#1824](https://github.com/pypa/pipx/issues/1824))
### Bugfixes
- Add regression coverage for `pipx inject` accepting `--force` before or after injected dependencies. ([#1444](https://github.com/pypa/pipx/issues/1444))
### Improved Documentation
- Use the bootstrap pipx executable when adding PATH in self-managed installs. ([#1481](https://github.com/pypa/pipx/issues/1481))
## [1.13.0](https://github.com/pypa/pipx/tree/1.13.0) - 2026-05-30
### Features
- Add `PIPX_DISABLE_SHARED_LIBS_AUTO_UPGRADE` to skip automatic shared library upgrades. ([#1650](https://github.com/pypa/pipx/issues/1650))
- Update the error message in get-pipx.py; it is obsoleted, not deprecated. ([#1813](https://github.com/pypa/pipx/issues/1813))
### Bugfixes
- Install app scripts with shebangs that ignore `PYTHONPATH`. ([#1584](https://github.com/pypa/pipx/issues/1584))
- Refresh cached standalone Python indexes written by older pipx versions before using `--fetch-missing-python`. ([#1774](https://github.com/pypa/pipx/issues/1774))
### Improved Documentation
- Document how to clear cache warnings from `runpip`. ([#1802](https://github.com/pypa/pipx/issues/1802))
## [1.12.0](https://github.com/pypa/pipx/tree/1.12.0) - 2026-05-06
### Features
- Add `--fetch-python` and `PIPX_FETCH_PYTHON` to control standalone Python downloads, with values `always`, `missing`, or
`never`. ([#1663](https://github.com/pypa/pipx/issues/1663))
- Add an opt-in `uv` backend. Install `pipx[uv]` (or put `uv` on `PATH`) and pipx will create venvs with `uv venv`, manage
packages with `uv pip`, and run ephemeral apps via `uv tool run`.
**Default change:** when `uv` is reachable, pipx uses it for **new** venvs by default. Existing venvs keep their
recorded backend; flipping a venv requires `pipx reinstall NAME --backend X`. Set `PIPX_DEFAULT_BACKEND=pip` to force
pip even when uv is available, or pass `--backend pip` per command. `pipx install pip` always picks the pip backend (uv
venvs have no pip).
Selection precedence: `--backend` > recorded venv metadata > `PIPX_DEFAULT_BACKEND` > auto-detect. The env var sits
*below* metadata so setting `PIPX_DEFAULT_BACKEND=uv` does not silently retarget existing pip-backed venvs; the recorded
backend wins until you flip it explicitly. `pipx environment` exposes the resolved backend and its source as
`PIPX_RESOLVED_BACKEND` and `PIPX_BACKEND_SOURCE`.
**Metadata version bump:** the venv metadata file format moves from `0.5` to `0.6` to record the chosen backend. Running
this pipx version against an existing venv rewrites its metadata to `0.6` on the next install/upgrade. If you downgrade
pipx after that, the older version raises `Unknown metadata version 0.6` and you'll need to reinstall the affected venvs
from the older pipx (`pipx reinstall NAME`). ([#1808](https://github.com/pypa/pipx/issues/1808))
### Deprecations and Removals
- Deprecate `--fetch-missing-python` and `PIPX_FETCH_MISSING_PYTHON`; both are now aliases for `--fetch-python=missing` /
`PIPX_FETCH_PYTHON=missing`. `PIPX_FETCH_MISSING_PYTHON=0` (and other falsy values) now disables fetching, where
previously any value enabled it. The `pipx.interpreter.find_python_interpreter` keyword `fetch_missing_python: bool` is
replaced by `fetch_python: FetchPythonOptions`. ([#1663](https://github.com/pypa/pipx/issues/1663))
## [1.11.2](https://github.com/pypa/pipx/tree/1.11.2) - 2026-05-05
### Features
- Add ``pipx help`` and ``pipx help `` aliases for existing help output. ([#1535](https://github.com/pypa/pipx/issues/1535))
- Drop support for Python 3.9. ([#1786](https://github.com/pypa/pipx/issues/1786))
- Replace if/elif command dispatch in main.py with argparse set_defaults. ([#1794](https://github.com/pypa/pipx/issues/1794))
## [1.11.1](https://github.com/pypa/pipx/tree/1.11.1) - 2026-03-31
### Bugfixes
- Ignore `PIP_TARGET` environment variable to prevent pip from installing outside the venv. ([#735](https://github.com/pypa/pipx/issues/735))
- Fix `pipx install` failing on Windows when the username contains non-Latin characters (e.g. cyrillic, Chinese). ([#780](https://github.com/pypa/pipx/issues/780))
- Show installed version and suggest `upgrade` when `install` detects an existing installation. ([#795](https://github.com/pypa/pipx/issues/795))
- `--verbose` and `--quiet` flags before the subcommand are no longer silently ignored. ([#1282](https://github.com/pypa/pipx/issues/1282))
- Remove dependency app symlinks when uninjecting a package that was injected with `--include-deps`. ([#1364](https://github.com/pypa/pipx/issues/1364))
- Remove `setuptools` from shared libs to prevent version conflicts when app venvs use a different Python. ([#1539](https://github.com/pypa/pipx/issues/1539))
- Prevent `uninject` from removing dependencies still needed by other packages in the venv. ([#1672](https://github.com/pypa/pipx/issues/1672))
## [1.11.0](https://github.com/pypa/pipx/tree/1.11.0) - 2026-03-23
### Features
- Add `PIPX_MAX_LOGS` environment variable to configure the maximum number of log files to keep. ([#1570](https://github.com/pypa/pipx/issues/1570))
### Bugfixes
- Allow `--pip-args` to be passed to `upgrade-all`. ([#1503](https://github.com/pypa/pipx/issues/1503))
- Fix `--pip-args='-c '` breaking when constraint target is a URL instead of a local path. ([#1582](https://github.com/pypa/pipx/issues/1582))
- Enable keyring authentication for private package indexes by setting `PIP_KEYRING_PROVIDER=subprocess` ([#1603](https://github.com/pypa/pipx/issues/1603))
- Added error handling for `pip list` command failures ([#1698](https://github.com/pypa/pipx/issues/1698))
### Improved Documentation
- Remove outdated "experimental" note from `--suffix` help text. ([#1621](https://github.com/pypa/pipx/issues/1621))
## [1.10.1](https://github.com/pypa/pipx/tree/1.10.1) - 2026-03-20
### Bugfixes
- Use stored pip_args from install metadata when running `pipx upgrade` without explicit `--pip-args` ([#1441](https://github.com/pypa/pipx/issues/1441))
- Fix `--global` flag being silently ignored when placed before the subcommand ([#1443](https://github.com/pypa/pipx/issues/1443))
- Respect `--quiet` flag in `install` and suppress animations and success messages ([#1508](https://github.com/pypa/pipx/issues/1508))
- Catch missing Python interpreter in `upgrade` and show helpful error instead of crashing ([#1602](https://github.com/pypa/pipx/issues/1602))
- Prevent data loss by rejecting relative paths in `uninstall`, `reinstall`, and other package-name arguments ([#1718](https://github.com/pypa/pipx/issues/1718))
## [1.10.0](https://github.com/pypa/pipx/tree/1.10.0) - 2026-03-18
### Features
- Add `--with` flag to `pipx run` to allow injecting dependencies ([#1607](https://github.com/pypa/pipx/issues/1607))
- add more specific directions in the logs towards a resolution if you have a space in the PIX_HOME path ([#1634](https://github.com/pypa/pipx/issues/1634))
### Bugfixes
- Fixed upgrade command failing when package name includes extras (e.g., `pipx upgrade "coverage[toml]"`). ([#925](https://github.com/pypa/pipx/issues/925))
- Fix run command with bash substitution (e.g. `pipx run <(pbpaste)`) ([#1293](https://github.com/pypa/pipx/issues/1293))
- Allow `pipx runpip` to split single string arguments. ([#1520](https://github.com/pypa/pipx/issues/1520))
- Fix handling of shared libraries when the original Python interpreter is removed on Windows by detecting stale venv references and recreating the shared libraries with the current Python. ([#1723](https://github.com/pypa/pipx/issues/1723))
### Misc
- [#1638](https://github.com/pypa/pipx/issues/1638), [#1731](https://github.com/pypa/pipx/issues/1731)
## [1.9.0](https://github.com/pypa/pipx/tree/1.9.0) - 2026-03-17
### Features
- Add completion choices for `pipx environment --value`. ([#1498](https://github.com/pypa/pipx/issues/1498))
### Bugfixes
- Ignore recursive symlink loops in PIPX_BIN_DIR. ([#1592](https://github.com/pypa/pipx/issues/1592))
- `pipx reinstall`: An exception will now be raised if package is pinned. ([#1611](https://github.com/pypa/pipx/issues/1611))
- Stop `pipx run` from leaving bad temporary venvs when first installation was unsuccessful. ([#1709](https://github.com/pypa/pipx/issues/1709))
## [1.8.0](https://github.com/pypa/pipx/tree/1.8.0) - 2025-09-30
### Features
- Rename environmental variable `USE_EMOJI` to `PIPX_USE_EMOJI`. ([#1395](https://github.com/pypa/pipx/issues/1395))
- Add `--all-shells` flag to `pipx ensurepath`. ([#1585](https://github.com/pypa/pipx/issues/1585))
- Add support for Python 3.13 ([#1647](https://github.com/pypa/pipx/issues/1647))
### Bugfixes
- On Windows, no longer overwrite existing files on upgrade if source and destination are the same ([#683](https://github.com/pypa/pipx/issues/683))
- Update the logic of finding python interpreter such that `--fetch-missing-python` works on Windows ([#1521](https://github.com/pypa/pipx/issues/1521))
- Fix no message displayed when no packages are upgraded with `upgrade-all`. ([#1565](https://github.com/pypa/pipx/issues/1565))
- Fix incorrect order of flags when using `pipx upgrade`. ([#1610](https://github.com/pypa/pipx/issues/1610))
- Update the archive name of build of Python for Windows ([#1630](https://github.com/pypa/pipx/issues/1630))
- Set up standalone python fetching to use checksums directly from the GitHub API. ([#1652](https://github.com/pypa/pipx/issues/1652))
- Fix running a script with explicitly empty ``dependencies = []``. ([#1658](https://github.com/pypa/pipx/issues/1658))
### Improved Documentation
- Fix `/changelog/` and `/contributing/` docs URLs ([#1540](https://github.com/pypa/pipx/issues/1540))
## [1.7.1](https://github.com/pypa/pipx/tree/1.7.1) - 2024-08-23
### Bugfixes
- Use minimum supported Python to build zipapp in release action such that `tomli` is included in it. ([#1514](https://github.com/pypa/pipx/issues/1514))
## [1.7.0](https://github.com/pypa/pipx/tree/1.7.0) - 2024-08-22
### Features
- Add a `--prepend` option to the `pipx ensurepath` command to allow prepending `pipx`'s location to `PATH` rather than appending to it. This is useful when you want to prioritize `pipx`'s executables over other executables in your `PATH`. ([#1451](https://github.com/pypa/pipx/issues/1451))
- List `PIPX_GLOBAL_[HOME|BIN_DIR|MAN_DIR]` in `pipx environment`. ([#1492](https://github.com/pypa/pipx/issues/1492))
### Bugfixes
- Introduce `PIPX_HOME_ALLOW_SPACE` environment variable, to silence the spaces in pipx home path warning ([#1320](https://github.com/pypa/pipx/issues/1320))
- Fix passing constraints file path into `pipx install` operation via `pip` args ([#1389](https://github.com/pypa/pipx/issues/1389))
- Add help messages for `pipx pin` and `pipx unpin` commands. ([#1438](https://github.com/pypa/pipx/issues/1438))
- Stop `pipx install --global` from installing files in `~/.local`. ([#1475](https://github.com/pypa/pipx/issues/1475))
- Fix installation abortion on multiple packages when one or more are already installed. ([#1509](https://github.com/pypa/pipx/issues/1509))
### Improved Documentation
- Move all documentation files to the `docs` directory. ([#1479](https://github.com/pypa/pipx/issues/1479))
## [1.6.0](https://github.com/pypa/pipx/tree/1.6.0) - 2024-06-01
### Features
- Add `install-all` command to install packages according to spec metadata file. ([#687](https://github.com/pypa/pipx/issues/687))
- Introduce `pipx pin` and `pipx unpin` commands, which can be used to pin or unpin the version
of an installed package, so it will not be upgraded by `pipx upgrade` or `pipx upgrade-all`. ([#891](https://github.com/pypa/pipx/issues/891))
- Add a new option `--pinned` to `pipx list` command for listing pinned packages only. ([#891](https://github.com/pypa/pipx/issues/891))
- Add `pipx interpreter upgrade` command to upgrade local standalone python in micro/patch level ([#1249](https://github.com/pypa/pipx/issues/1249))
- Add `--requirement` option to `inject` command to read list of packages from a text file. ([#1252](https://github.com/pypa/pipx/issues/1252))
- Add `pipx upgrade-shared` command, to create/upgrade shared libraries as a standalone command. ([#1316](https://github.com/pypa/pipx/issues/1316))
- Allow `upgrade` command to accept multiple packages as arguments. ([#1336](https://github.com/pypa/pipx/issues/1336))
- Support Python version for `--python` arg when py launcher is not available ([#1342](https://github.com/pypa/pipx/issues/1342))
- Make `install-all` gather errors in batch ([#1348](https://github.com/pypa/pipx/issues/1348))
### Bugfixes
- Resolve the `DEFAULT_PYTHON` to the actual absolute path ([#965](https://github.com/pypa/pipx/issues/965))
- Fix error log overwrite for "-all" batch operations. ([#1132](https://github.com/pypa/pipx/issues/1132))
- Do not reinstall already injected packages without `--force` being passed. ([#1300](https://github.com/pypa/pipx/issues/1300))
- Only show `--python` and `--force` flag warning if both flags are present ([#1304](https://github.com/pypa/pipx/issues/1304))
- Don't allow paths to be passed into `pipx reinstall`, as this might wreak havoc. ([#1324](https://github.com/pypa/pipx/issues/1324))
- Make the Python `venv` module arguments work with `upgrade --install` ([#1344](https://github.com/pypa/pipx/issues/1344))
- Fix version check for standalone python ([#1349](https://github.com/pypa/pipx/issues/1349))
- Validate package(s) argument should not be path(s). ([#1354](https://github.com/pypa/pipx/issues/1354))
- Validate whether a package is an URL correctly. ([#1355](https://github.com/pypa/pipx/issues/1355))
- Support python3.8 for standalone python builds ([#1375](https://github.com/pypa/pipx/issues/1375))
- Install specified version of `--preinstall` dependency instead of latest version ([#1377](https://github.com/pypa/pipx/issues/1377))
- Move `--global` option into shared parser, such that it can be passed after the subcommand, for example `pipx ensurepath --global`. ([#1397](https://github.com/pypa/pipx/issues/1397))
- Fix discovery of a `pipx run` entry point if a local path was given as package. ([#1422](https://github.com/pypa/pipx/issues/1422))
### Improved Documentation
- Create a dedicated section for manual pages and add an example with `pdm-backend`. ([#1312](https://github.com/pypa/pipx/issues/1312))
- Add example, test and cli help description how to install multiple packages with the --preinstall flag ([#1321](https://github.com/pypa/pipx/issues/1321))
- Refine docs generation script and template. ([#1325](https://github.com/pypa/pipx/issues/1325))
- Add a note about sourcing the shell config file for `ensure_path` ([#1346](https://github.com/pypa/pipx/issues/1346))
## [1.5.0](https://github.com/pypa/pipx/tree/1.5.0) - 2024-03-29
### Features
- Add `--global` option to `pipx` commands.
- This will run the action in a global scope and affect environment for all system users. ([#754](https://github.com/pypa/pipx/issues/754))
- Add a `--fetch-missing-python` flag to all commands that accept a `--python` flag.
- When combined, this will automatically download a standalone copy of the requested python version if it's not already available on the user's system. ([#1242](https://github.com/pypa/pipx/issues/1242))
- Add commands to list and prune standalone interpreters ([#1248](https://github.com/pypa/pipx/issues/1248))
- Revert platform-specific directories on MacOS and Windows
- They were leading to a lot of issues with Windows sandboxing and spaces in shebangs on MacOS. ([#1257](https://github.com/pypa/pipx/issues/1257))
- Add `--install` option to `pipx upgrade` command.
- This will install the package given as argument if it is not already installed. ([#1262](https://github.com/pypa/pipx/issues/1262))
### Bugfixes
- Correctly resolve home directory in pipx directory environment variables. ([#94](https://github.com/pypa/pipx/issues/94))
- Pass through `pip` arguments when upgrading shared libraries. ([#964](https://github.com/pypa/pipx/issues/964))
- Fix installation issues when files in the working directory interfere with venv creation process. ([#1091](https://github.com/pypa/pipx/issues/1091))
- Report correct filename in tracebacks with `pipx run ` ([#1191](https://github.com/pypa/pipx/issues/1191))
- Let self-managed pipx uninstall itself on windows again. ([#1203](https://github.com/pypa/pipx/issues/1203))
- Fix path resolution for python executables looked up in PATH on windows. ([#1205](https://github.com/pypa/pipx/issues/1205))
- Display help message when `pipx install` is run without arguments. ([#1266](https://github.com/pypa/pipx/issues/1266))
- Fix crashes due to superfluous `-q ` flags by discarding exceeding values ([#1283](https://github.com/pypa/pipx/issues/1283))
### Improved Documentation
- Update the completion instructions for zipapp users. ([#1072](https://github.com/pypa/pipx/issues/1072))
- Update the example for running scripts with dependencies. ([#1227](https://github.com/pypa/pipx/issues/1227))
- Update the docs for package developers on the use of configuration using pyproject.toml ([#1229](https://github.com/pypa/pipx/issues/1229))
- Add installation instructions for Fedora ([#1239](https://github.com/pypa/pipx/issues/1239))
- Update the examples for installation from local dir ([#1277](https://github.com/pypa/pipx/issues/1277))
- Fix inconsistent wording in `pipx install` command description. ([#1307](https://github.com/pypa/pipx/issues/1307))
### Deprecations and Removals
- Deprecate `--skip-maintenance` flag of `pipx list`; maintenance is now never executed there ([#1256](https://github.com/pypa/pipx/issues/1256))
### Misc
- [#1296](https://github.com/pypa/pipx/issues/1296)
## [1.4.3](https://github.com/pypa/pipx/tree/1.4.3) - 2024-01-16
### Bugfixes
- Autofix python version for pylauncher, when version is provided prefixed with `python` ([#1150](https://github.com/pypa/pipx/issues/1150))
- Support building pipx wheels with setuptools-scm<7, such as on FreeBSD. ([#1208](https://github.com/pypa/pipx/issues/1208))
### Improved Documentation
- Provide useful error messages when unresolvable python version is passed ([#1150](https://github.com/pypa/pipx/issues/1150))
- Introduce towncrier for managing the changelog ([#1161](https://github.com/pypa/pipx/issues/1161))
- Add workaround for using pipx applications in shebang under macOS ([#1198](https://github.com/pypa/pipx/issues/1198))
## [1.4.2](https://github.com/pypa/pipx/tree/1.4.2)
### Features
- Allow skipping maintenance tasks during list command
- Raise more user friendly error when provided `--python` version is not found
- Update `pipx run` on scripts using `/// script` and no `run` table following the updated version of PEP 723 (#1180)
### Bugfixes
- Include `tomli` into `pipx.pyz` (zipapp) so that it can be executed with Python 3.10 or earlier (#1142)
- Fix resolving the python executable path on linux
- `pipx run`: Verify whether the script name provided is a file before running it
- Avoid repeated exception logging in a few rare cases (#1192)
## [1.4.1](https://github.com/pypa/pipx/tree/1.4.1)
### Bugfixes
- Set default logging level to WARNING, so debug log messages won't be shown without passing additional flags such as `--verbose`
## [1.4.0](https://github.com/pypa/pipx/tree/1.4.0)
### Features
- Add `--quiet` and `--verbose` options for the `pipx` subcommands
- Add ability to install multiple packages at once
- Delete directories directly instead of spawning rmdir on Windows
### Improved Documentation
- Add Scoop installation instructions
### Bugfixes
- "Failed to delete" error when using Microsoft Store Python
- "No pyvenv.cfg file" error when using Microsoft Store Python (#1164)
## [1.3.3](https://github.com/pypa/pipx/tree/1.3.3)
### Improved Documentation
- Make the logo more visible in dark mode
## [1.3.2](https://github.com/pypa/pipx/tree/1.3.2)
### Features
- The project version number is now dynamic and generated from the VCS at build time
### Improved Documentation
- Add additional example for --pip-args option, to docs/examples.md
## [1.3.1](https://github.com/pypa/pipx/tree/1.3.1)
### Bugfixes
- Fix combining of --editable and --force flag
## [1.3.0](https://github.com/pypa/pipx/tree/1.3.0)
### Features
- Allow running `pip` with `pipx run`
- Add `--with-suffix` for `pipx inject` command
- `pipx install`: emit a warning when `--force` and `--python` were passed at the same time
- Add explicit 3.12 support
- Make usage message in `pipx run` show `package_or_url`, so extra will be printed out as well
- Use the py launcher, if available, to select Python version with the `--python` option
- add pre-commit hook support
- Add `pipx install --preinstall` to support preinstalling build requirements
- Return an error message when directory can't be added to PATH successfully
- Expose manual pages included in an application installed with `pipx install`
- Check whether pip module exists in shared lib before performing any actions, such as `reinstall-all`.
- Drop `setuptools` and `wheel` from the shared libraries. This results in less time consumption when the libraries are
automatically upgraded.
- Support [inline script metadata](https://packaging.python.org/en/latest/specifications/inline-script-metadata/)
in `pipx run`.
- Imply `--include-apps` when running `pipx inject --include-deps`
- Add `--force-reinstall` to pip arguments when `--force` was passed
- Support including requirements in scripts run using `pipx run` (#916)
- Pass `pip_args` to `shared_libs.upgrade()`
- Fallback to user's log path if the default log path (`$PIPX_HOME/logs`) is not writable to aid with pipx being used
for multi-user (e.g. system-wide) installs of applications
- Don't show escaped backslashes for paths in console output
- Move `pipx` paths to ensure compatibility with the platform-specific user directories
- Pass `--no-input` to pip when output is not piped to parent stdout
- Print all environment variables in `pipx environment`
### Improved Documentation
- Add more examples for `pipx run`
- Add subsection to make README easier to read
### Deprecations and Removals
- Drop support for Python 3.7
### Bugfixes
- Fix wrong interpreter usage when injecting local pip-installable dependencies into venvs
- Fix program name in generated manual page
## [1.2.1](https://github.com/pypa/pipx/tree/1.2.1)
### Bugfixes
- Fix compatibility to packaging 23.2+ by removing reliance on packaging's requirement validation logic and detecting a
URL-based requirement in pipx. (#1070)
## [1.2.0](https://github.com/pypa/pipx/tree/1.2.0)
### Features
- Add `pipx uninject` command (#820)
- Ship a [zipapp](https://docs.python.org/3/library/zipapp.html) of pipx
- Match pip's behaviour when package name ends with archive extension (treat it as a path)
- Change the program name to `path/to/python -m pipx` when running as `python -m pipx`
- Improve the detection logic for MSYS2 to avoid entering infinite loop (#908) (#938)
- Remove extra trailing quote from exception message
- Fix EncodingWarning in `pipx_metadata_file`.
### Improved Documentation
- Add an example for installation from source with extras
- Fix `pipx run` examples and update Python versions used by `pipx install` examples
### Bugfixes
- Add test for pip module in `pipx reinstall` to fix an issue with `pipx reinstall-all` (#935)
## [1.1.0](https://github.com/pypa/pipx/tree/1.1.0)
### Features
- Add `pipx environment` command (#793)
- Add `list --short` option to list only package names (#804)
- Improve the behaviour of `shlex.split` on Windows, so paths on Windows can be handled properly when they are passed in
`--pip-args`. (#794)
- [dev] Change github action job names
- Add additional examples for installation from git repos
- [packaging] Switch to [PEP 621](https://www.python.org/dev/peps/pep-0621/)
- Add a CACHEDIR.TAG to the cache directory to prevent it from being included in archives and backups. For more
information about cache directory tags, see https://bford.info/cachedir
### Bugfixes
- Fix encoding issue on Windows when pip fails to install a package
### Improved Documentation
- Add more examples
- Fix the command for
[installing development version](https://pipx.pypa.io/stable/installation/#install-pipx-development-versions). (#801)
- Fix test status badge in readme file
## [1.0.0](https://github.com/pypa/pipx/tree/1.0.0)
### Features
- Support [argcomplete 2.0.0](https://pypi.org/project/argcomplete/2.0.0) (#790)
- Include machinery to build a manpage for pipx with [argparse-manpage](https://pypi.org/project/argparse-manpage/).
- Add better handling for 'app not found' when a single app is present in the project, and an improved error message
(#733)
### Bugfixes
- Fixed animations sending output to stdout, which can break JSON output. (#769)
- Fix typo in `pipx upgrade-all` output
## [0.17.0](https://github.com/pypa/pipx/tree/0.17.0)
- Support `pipx run` with version constraints and extras. (#697)
## [0.16.5](https://github.com/pypa/pipx/tree/0.16.5)
- Fixed `pipx list` output phrasing to convey that python version displayed is the one with which package was installed.
- Fixed `pipx install` to provide return code 0 if venv already exists, similar to pipโs behavior. (#736)
- [docs] Update ansible's install command in
[Programs to Try document](https://pipx.pypa.io/stable/programs-to-try/#ansible) to work with Ansible 2.10+ (#742)
## [0.16.4](https://github.com/pypa/pipx/tree/0.16.4)
- Fix to `pipx ensurepath` to fix behavior in user locales other than UTF-8, to fix #644. The internal change is to use
userpath v1.6.0 or greater. (#700)
- Fix virtual environment inspection for Python releases that uses an int for its release serial number. (#706)
- Fix PermissionError in windows when pipx manages itself. (#718)
## [0.16.3](https://github.com/pypa/pipx/tree/0.16.3)
- Organization: pipx is extremely pleased to now be a project of the Python Packaging Authority (PyPA)! Note that our
github URL has changed to [pypa/pipx](https://github.com/pypa/pipx)
- Fixed `pipx list --json` to return valid json with no venvs installed. Previously would return an empty string to
stdout. (#681)
- Changed `pipx ensurepath` bash behavior so that only one of {`~/.profile`, `~/.bash\_profile`} is modified with the
extra pipx paths, not both. Previously, if a `.bash_profile` file was created where one didn't exist, it could cause
problems, e.g. #456. The internal change is to use userpath v1.5.0 or greater. (#684)
- Changed default nox tests, Github Workflow tests, and pytest behavior to use local pypi server with fixed lists of
available packages. This allows greater test isolation (no network pypi access needed) and determinism (fixed
available dependencies.) It also allows running the tests offline with some extra preparation beforehand (See
[Running Unit Tests Offline](https://pipx.pypa.io/stable/contributing/#running-unit-tests-offline)). The old style
tests that use the internet to access pypi.org are still available using `nox -s tests_internet` or
`pytest --net-pypiserver tests`. (#686)
* Colorama is now only installed on Windows. (#691)
## [0.16.2.1](https://github.com/pypa/pipx/tree/0.16.2.1)
- Changed non-venv-info warnings and notices from `pipx list` to print to stderr. This especially prevents
`pipx list --json` from printing invalid json to stdout. (#680)
- Fixed bug that could cause uninstall on Windows with injected packages to uninstall too many apps from the local
binary directory. (#679)
## [0.16.2.0](https://github.com/pypa/pipx/tree/0.16.2.0)
- Fixed bug #670 where uninstalling a venv could erroneously uninstall other apps from the local binary directory.
(#672)
- Added `--json` switch to `pipx list` to output rich json-metadata for all venvs.
- Ensured log files are utf-8 encoded to prevent Unicode encoding errors from occurring with emojis. (#646)
- Fixed issue which made pipx incorrectly list apps as part of a venv when they were not installed by pipx. (#650)
- Fixed old regression that would prevent pipx uninstall from cleaning up linked binaries if the venv was old and did
not have pipx metadata. (#651)
- Fixed bugs with suffixed-venvs on Windows. Now properly summarizes install, and actually uninstalls associated
binaries for suffixed-venvs. (#653)
- Changed venv minimum python version to 3.6, removing python 3.5 which is End of Life. (#666)
## [0.16.1.0](https://github.com/pypa/pipx/tree/0.16.1.0)
- Introduce the `pipx.run` entry point group as an alternative way to declare an application for `pipx run`.
- Fix cursor show/hide to work with older versions of Windows. (#610)
- Support text colors on Windows. (#612)
- Better platform unicode detection to avoid errors and allow showing emojis when possible. (#614)
- Don't emit show cursor or hide cursor codes if STDERR is not a tty. (#620)
- Sped up `pipx list` (#624).
- pip errors no longer stream to the shell when pip fails during a pipx install. pip's output is now saved to a log
file. In the shell, pipx will tell you the location of the log file and attempt to summarize why pip failed. (#625)
- For `reinstall-all`, fixed bug where missing python executable would cause error. (#634)
- Fix regression which prevented pipx from working with pythonloc (and `__pypackages__` folder). (#636)
## [0.16.0.0](https://github.com/pypa/pipx/tree/0.16.0.0)
- New venv inspection! The code that pipx uses to examine and determine metadata in an installed venv has been made
faster, better, and more reliable. It now uses modern python libraries like `packaging` and `importlib.metadata` to
examine installed venvs. It also now properly handles installed package extras. In addition, some problems pipx has
had with certain characters (like periods) in package names should be remedied.
- Added reinstall command for reinstalling a single venv.
- Changed `pipx run` on non-Windows systems to actually replace pipx process with the app process instead of running it
as a subprocess. (Now using python's `os.exec*`)
- [bugfix] Fixed bug with reinstall-all command when package have been installed using a specifier. Now the initial
specifier is used.
- [bugfix] Override display of `PIPX_DEFAULT_PYTHON` value when generating web documentation for `pipx install` #523
- [bugfix] Wrap help documentation for environment variables.
- [bugfix] Fixed uninstall crash that could happen on Windows for certain packages
- [feature] Venv package name arguments now do not have to match exactly as pipx has them stored, but can be specified
in any python-package-name-equivalent way. (i.e. case does not matter, and `.`, `-`, `_` characters are
interchangeable.)
- [change] Venvs with a suffix: A suffix can contain any characters, but for purposes of uniqueness, python package name
rules apply--upper- and lower-case letters are equivalent, and any number of `.`, `-`, or `_` characters in a row are
equivalent. (e.g. if you have a suffixed venv `pylint_1.0A` you could not add another suffixed venv called
`pylint--1-0a`, as it would not be a unique name.)
- [implementation detail] Pipx shared libraries (providing pip, setuptools, wheel to pipx) are no longer installed using
pip arguments taken from the last regular pipx install. If you need to apply pip arguments to pipx's use of pip for
its internal shared libraries, use PIP\_\* environment variables.
- [feature] Autocomplete for venv names is no longer restricted to an exact match to the literal venv name, but will
autocomplete any logically-similar python package name (i.e. case does not matter, and `.`, `-`, `_` characters are
all equivalent.)
- pipx now reinstall its internal shared libraries when the user executes `reinstall-all`.
- Made sure shell exit codes from every pipx command are correct. In the past some (like from `pipx upgrade`) were
wrong. The exit code from `pipx runpip` is now the exit code from the `pip` command run. The exit code from
`pipx list` will be 1 if one or more venvs have problems that need to be addressed.
- pipx now writes a log file for each pipx command executed to `$PIPX_HOME/logs`, typically `~/.local/pipx/logs`. pipx
keeps the most recent 10 logs and deletes others.
- `pipx upgrade` and `pipx upgrade-all` now have a `--upgrade-injected` option which directs pipx to also upgrade
injected packages.
- `pipx list` now detects, identifies, and suggests a remedy for venvs with old-internal data (internal venv names) that
need to be updated.
- Added a "Troubleshooting" page to the pipx web documentation for common problems pipx users may encounter.
- pipx error, warning, and other messages now word-wrap so words are not split across lines. Their appearance is also
now more consistent.
## [0.15.6.0](https://github.com/pypa/pipx/tree/0.15.6.0)
- [docs] Update license
- [docs] Display a more idiomatic command for registering completions on fish.
- [bugfix] Fixed regression in list, inject, upgrade, reinstall-all commands when suffixed packages are used.
- [bugfix] Do not reset package url during upgrade when main package is `pipx`
- Updated help text to show description for `ensurepath` and `completions` help
- Added support for user-defined default python interpreter via new `PIPX_DEFAULT_PYTHON`. Helpful for use with pyenv
among other uses.
- [bugfix] Fixed bug where extras were ignored with a PEP 508 package specification with a URL.
## [0.15.5.1](https://github.com/pypa/pipx/tree/0.15.5.1)
- [bugfix] Fixed regression of 0.15.5.0 which erroneously made installing from a local path with package extras not
possible.
## [0.15.5.0](https://github.com/pypa/pipx/tree/0.15.5.0)
- pipx now parses package specification before install. It removes (with warning) the `--editable` install option for
any package specification that is not a local path. It also removes (with warning) any environment markers.
- Disabled animation when we cannot determine terminal size or if the number of columns is too small. (Fixes #444)
- [feature] Version of each injected package is now listed after name for `pipx list --include-injected`
- Change metadata recorded from version-specified install to allow upgrades in future. Adds pipx dependency on
`packaging` package.
- [bugfix] Prevent python error in case where package has no pipx metadata and advise user how to fix.
- [feature] `ensurepath` now also ensures that pip user binary path containing pipx itself is in user's PATH if pipx was
installed using `pip install --user`.
- [bugfix] For `pipx install`, fixed failure to install if user has `PIP_USER=1` or `user=true` in pip.conf. (#110)
- [bugfix] Requiring userpath v1.4.1 or later so ensure Windows bug is fixed for `ensurepath` (#437)
- [feature] log pipx version (#423)
- [feature] `--suffix` option for `install` to allow multiple versions of same tool to be installed (#445)
- [feature] pipx can now be used with the Windows embeddable Python distribution
## [0.15.4.0](https://github.com/pypa/pipx/tree/0.15.4.0)
- [feature] `list` now has a new option `--include-injected` to show the injected packages in the main apps
- [bugfix] Fixed bug that can cause crash when installing an app
## [0.15.3.1](https://github.com/pypa/pipx/tree/0.15.3.1)
- [bugfix] Workaround multiprocessing issues on certain platforms (#229)
## [0.15.3.0](https://github.com/pypa/pipx/tree/0.15.3.0)
- [feature] Use symlinks on Windows when symlinks are available
## [0.15.2.0](https://github.com/pypa/pipx/tree/0.15.2.0)
- [bugfix] Improved error reporting during venv metadata inspection.
- [bugfix] Fixed incompatibility with pypy as venv interpreter (#372).
- [bugfix] Replaced implicit dependency on setuptools with an explicit dependency on packaging (#339).
- [bugfix] Continue reinstalling packages after failure
- [bugfix] Hide cursor while pipx runs
- [feature] Add environment variable `USE_EMOJI` to allow enabling/disabling emojis (#376)
- [refactor] Moved all commands to separate files within the commands module (#255).
- [bugfix] Ignore system shared libraries when installing shared libraries pip, wheel, and setuptools. This also fixes
an incompatibility with Debian/Ubuntu's version of pip (#386).
## [0.15.1.3](https://github.com/pypa/pipx/tree/0.15.1.3)
- [bugfix] On Windows, pipx now lists correct Windows apps (#217)
- [bugfix] Fixed a `pipx install` bug causing incorrect python binary to be used when using the optional --python
argument in certain situations, such as running pipx from a Framework python on macOS and specifying a non-Framework
python.
## [0.15.1.2](https://github.com/pypa/pipx/tree/0.15.1.2)
- [bugfix] Fix recursive search of dependencies' apps so no apps are missed.
- `upgrade-all` now skips editable packages, because pip disallows upgrading editable packages.
## [0.15.1.1](https://github.com/pypa/pipx/tree/0.15.1.1)
- [bugfix] fix regression that caused installing with --editable flag to fail package name determination.
## [0.15.1.0](https://github.com/pypa/pipx/tree/0.15.1.0)
- Add Python 3.8 to PyPI classifier and travis test matrix
- [feature] auto-upgrade shared libraries, including pip, if older than one month. Hide all pip warnings that a new
version is available. (#264)
- [bugfix] pass pip arguments to pip when determining package name (#320)
## [0.15.0.0](https://github.com/pypa/pipx/tree/0.15.0.0)
Upgrade instructions: When upgrading to 0.15.0.0 or above from a pre-0.15.0.0 version, you must re-install all packages
to take advantage of the new persistent pipx metadata files introduced in this release. These metadata files store pip
specification values, injected packages, any custom pip arguments, and more in each main package's venv. You can do this
by running `pipx reinstall-all` or `pipx uninstall-all`, then reinstalling manually.
- `install` now has no `--spec` option. You may specify any valid pip specification for `install`'s main argument.
- `inject` will now accept pip specifications for dependency arguments
- Metadata is now stored for each application installed, including install options like `--spec`, and injected packages.
This information allows upgrade, upgrade-all and reinstall-all to work properly even with non-pypi installed packages.
(#222)
- `upgrade` options `--spec` and `--include-deps` were removed. Pipx now uses the original options used to install each
application instead. (#222)
- `upgrade-all` options `--include-deps`, `--system-site-packages`, `--index-url`, `--editable`, and `--pip-args` were
removed. Pipx now uses the original options used to install each application instead. (#222)
- `reinstall-all` options `--include-deps`, `--system-site-packages`, `--index-url`, `--editable`, and `--pip-args` were
removed. Pipx now uses the original options used to install each application instead. (#222)
- Handle missing interpreters more gracefully (#146)
- Change `reinstall-all` to use system python by default for apps. Now use `--python` option to specify a different
python version.
- Remove the PYTHONPATH environment variable when executing any command to prevent conflicts between pipx dependencies
and package dependencies when pipx is installed via homebrew. Homebrew can use PYTHONPATH manipulation instead of
virtual environments. (#233)
- Add printed summary after successful call to `pipx inject`
- Support associating apps with Python 3.5
- Improvements to animation status text
- Make `--python` argument in `reinstall-all` command optional
- Use threads on OS's without support for semaphores
- Stricter parsing when passing `--` argument as delimiter
## [0.14.0.0](https://github.com/pypa/pipx/tree/0.14.0.0)
- Speed up operations by using shared venv for `pip`, `setuptools`, and `wheel`. You can see more detail in the 'how
pipx works' section of the documentation. (#164, @pfmoore)
- Breaking change: for the `inject` command, change `--include-binaries` to `--include-apps`
- Change all terminology from `binary` to `app` or `application`
- Improve argument parsing for `pipx run` and `pipx runpip`
- If `--force` is passed, remove existing files in PIPX_BIN_DIR
- Move animation to start of line, hide cursor when animating
## [0.13.2.3](https://github.com/pypa/pipx/tree/0.13.2.3)
- Fix regression when installing a package that doesn't have any entry points
## [0.13.2.2](https://github.com/pypa/pipx/tree/0.13.2.2)
- Remove unnecessary and sometimes incorrect check after `pipx inject` (#195)
- Make status text/animation reliably disappear before continuing
- Update animation symbols
## [0.13.2.1](https://github.com/pypa/pipx/tree/0.13.2.1)
- Remove virtual environment if installation did not complete. For example, if it was interrupted by ctrl+c or if an
exception occurred for any reason. (#193)
## [0.13.2.0](https://github.com/pypa/pipx/tree/0.13.2.0)
- Add shell autocompletion. Also add `pipx completions` command to print instructions on how to add pipx completions to
your shell.
- Un-deprecate `ensurepath`. Use `userpath` internally instead of instructing users to run the `userpath` cli command.
- Improve detection of PIPX_BIN_DIR not being on PATH
- Improve error message when an existing symlink exists in PIPX_BIN_DIR and points to the wrong location
- Improve handling of unexpected files in PIPX_HOME (@uranusjr)
- swap out of order logic in order to correctly recommend --include-deps (@joshuarli)
- [dev] Migrate from tox to nox
## [0.13.1.1](https://github.com/pypa/pipx/tree/0.13.1.1)
- Do not raise bare exception if no binaries found (#150)
- Update pipsi migration script
## [0.13.1.0](https://github.com/pypa/pipx/tree/0.13.1.0)
- Deprecate `ensurepath` command. Use `userpath append ~/.local/bin`
- Support redirects and proxies when downloading python files (i.e. `pipx run http://url/file.py`)
- Use tox for document generation and CI testing (CI tests are now functional rather than static tests on style and
formatting!)
- Use mkdocs for documentation
- Change default cache duration for `pipx run` from 2 to 14 days
## [0.13.0.1](https://github.com/pypa/pipx/tree/0.13.0.1)
- Fix upgrade-all and reinstall-all regression
## [0.13.0.0](https://github.com/pypa/pipx/tree/0.13.0.0)
- Add `runpip` command to run arbitrary pip commands in pipx-managed virtual environments
- Do not raise error when running `pipx install PACKAGE` and the package has already been installed by pipx (#125). This
is the cause of the major version change from 0.12 to 0.13.
- Add `--skip` argument to `upgrade-all` and `reinstall-all` commands, to let the user skip particular packages
## [0.12.3.3](https://github.com/pypa/pipx/tree/0.12.3.3)
- Update logic in determining a package's binaries during installation. This removes spurious binaries from the
installation. (#104)
- Improve compatibility with Debian distributions by using `shutil.which` instead of `distutils.spawn.find_executable`
(#102)
## [0.12.3.2](https://github.com/pypa/pipx/tree/0.12.3.2)
- Fix infinite recursion error when installing package such as `cloudtoken==0.1.84` (#103)
- Fix windows type errors (#96, #98)
## [0.12.3.1](https://github.com/pypa/pipx/tree/0.12.3.1)
- Fix "WindowsPath is not iterable" bug
## [0.12.3.0](https://github.com/pypa/pipx/tree/0.12.3.0)
- Add `--include-deps` argument to include binaries of dependent packages when installing with pipx. This improves
compatibility with packages that depend on other installed packages, such as `jupyter`.
- Speed up `pipx list` output (by running multiple processes in parallel) and by collecting all metadata in a single
subprocess call
- More aggressive cache directory removal when `--no-cache` is passed to `pipx run`
- [dev] Move inline text passed to subprocess calls to their own files to enable autoformatting, linting, unit testing
## [0.12.2.0](https://github.com/pypa/pipx/tree/0.12.2.0)
- Add support for PEP 582's `__pypackages__` (experimental). `pipx run BINARY` will first search in `__pypackages__` for
binary, then fallback to installing from PyPI. `pipx run --pypackages BINARY` will raise an error if the binary is not
found in `__pypackages__`.
- Fix regression when installing with `--editable` flag (#93)
- [dev] improve unit tests
## [0.12.1.0](https://github.com/pypa/pipx/tree/0.12.1.0)
- Cache and reuse temporary Virtual Environments created with `pipx run` (#61)
- Update binary discovery logic to find "scripts" like awscli (#91)
- Forward `--pip-args` to the pip upgrade command (previously the args were forwarded to install/upgrade commands for
packages) (#77)
- When using environment variable PIPX_HOME, Virtual Environments will now be created at `$PIPX_HOME/venvs` rather than
at `$PIPX_HOME`.
- [dev] refactor into multiple files, add more unit tests
## [0.12.0.4](https://github.com/pypa/pipx/tree/0.12.0.4)
- Fix parsing bug in pipx run
## [0.12.0.3](https://github.com/pypa/pipx/tree/0.12.0.3)
- list python2 as supported language so that pip installs with python2 will no longer install the pipx on PyPI from the
original pipx owner. Running pipx with python2 will fail, but at least it will not be as confusing as running the pipx
package from the original owner.
## [0.12.0.2](https://github.com/pypa/pipx/tree/0.12.0.2)
- forward arguments to run command correctly #90
## [0.12.0.1](https://github.com/pypa/pipx/tree/0.12.0.1)
- stop using unverified context #89
## [0.12.0.0](https://github.com/pypa/pipx/tree/0.12.0.0)
- Change installation instructions to use `pipx` PyPI name
- Add `ensurepath` command
## [0.11.0.2](https://github.com/pypa/pipx/tree/0.11.0.2)
- add version argument parsing back in (fixes regression)
## [0.11.0.1](https://github.com/pypa/pipx/tree/0.11.0.1)
- add version check, command check, fix printed version update installation instructions
## [0.11.0.0](https://github.com/pypa/pipx/tree/0.11.0.0)
- Replace `pipx BINARY` with `pipx run BINARY` to run a binary in an ephemeral environment. This is a breaking API
change so the major version has been incremented. (Issue #69)
- upgrade pip when upgrading packages (Issue #72)
- support --system-site-packages flag (Issue #64)
## [0.10.4.1](https://github.com/pypa/pipx/tree/0.10.4.1)
- Fix version printed when `pipx --version` is run
## [0.10.4.0](https://github.com/pypa/pipx/tree/0.10.4.0)
- Add --index-url, --editable, and --pip-args flags
- Updated README with pipsi migration instructions
## [0.10.3.0](https://github.com/pypa/pipx/tree/0.10.3.0)
- Display python version in list
- Do not reinstall package if already installed (added `--force` flag to override)
- When upgrading all packages, print message only when package is updated
- Avoid accidental execution of pipx.**main**
pipx-1.14.0/docs/contributing.md 0000664 0000000 0000000 00000025112 15210205776 0016544 0 ustar 00root root 0000000 0000000 ---
hide:
- navigation
---
Thanks for your interest in contributing to pipx!
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).
## Submitting changes
1. Fork [the GitHub repository](https://github.com/pypa/pipx).
1. Make a branch off of `main` and commit your changes to it.
1. Add a changelog entry.
1. Submit a pull request to the `main` branch on GitHub, referencing an open issue.
### Changelog entries
The `CHANGELOG.md` file is built by [towncrier](https://pypi.org/project/towncrier/) from news fragments in the
`changelog.d/` directory. To add an entry, create a news fragment in that directory named `{number}.{type}.md`, where
`{number}` is the issue number, and `{type}` is one of `feature`, `bugfix`, `doc`, `removal`, or `misc`.
For example, if your issue number is 1234 and it's fixing a bug, then you would create `changelog.d/1234.bugfix.md`. PRs
can span multiple categories by creating multiple files: if you added a feature and deprecated/removed an old feature
for issue #5678, you would create `changelog.d/5678.feature.md` and `changelog.d/5678.removal.md`.
A changelog entry is meant for end users and should only contain details relevant to them. In order to maintain a
consistent style, please keep the entry to the point, in sentence case, shorter than 80 characters, and in an imperative
tone. An entry should complete the sentence "This change will ...". If one line is not enough, use a summary line in an
imperative tone, followed by a description of the change in one or more paragraphs, each wrapped at 80 characters and
separated by blank lines.
You don't need to reference the pull request or issue number in a changelog entry, since towncrier will add a link using
the number in the file name. Similarly, you don't need to add your name to the entry, since that will be associated with
the pull request.
## Codebase Architecture
All source code lives under `src/pipx/`. The CLI entry point is `main.py`, which dispatches to command modules in
`commands/`.
```mermaid
flowchart TD
MAIN["main.py CLI parser + dispatch"] --> CMDS["commands/"]
CMDS --> INSTALL["install.py"]
CMDS --> RUN["run.py"]
CMDS --> UPGRADE["upgrade.py"]
CMDS --> INJECT["inject.py"]
CMDS --> LIST["list_packages.py"]
CMDS --> PIN["pin.py"]
CMDS --> INTERP_CMD["interpreter.py"]
CMDS --> OTHER["uninstall, uninject, reinstall, ensure_path, environment, run_pip"]
MAIN --> VENV["venv.py Venv + VenvContainer"]
MAIN --> PATHS["paths.py PIPX_HOME resolution"]
VENV --> SHARED["shared_libs.py shared pip venv"]
VENV --> INSPECT["venv_inspect.py metadata reader"]
VENV --> META["pipx_metadata_file.py JSON persistence"]
RUN --> SPEC["package_specifier.py PEP 508 parsing"]
RUN --> INTERP["interpreter.py Python resolution"]
INTERP --> STANDALONE["standalone_python.py download builds"]
style MAIN fill:#3f72af,color:#fff
style CMDS fill:#2a9d8f,color:#fff
style INSTALL fill:#2a9d8f,color:#fff
style RUN fill:#2a9d8f,color:#fff
style UPGRADE fill:#2a9d8f,color:#fff
style INJECT fill:#2a9d8f,color:#fff
style LIST fill:#2a9d8f,color:#fff
style PIN fill:#2a9d8f,color:#fff
style INTERP_CMD fill:#2a9d8f,color:#fff
style OTHER fill:#2a9d8f,color:#fff
style VENV fill:#7c4dff,color:#fff
style PATHS fill:#c78c20,color:#fff
style SHARED fill:#c78c20,color:#fff
style INSPECT fill:#7c4dff,color:#fff
style META fill:#7c4dff,color:#fff
style SPEC fill:#388e3c,color:#fff
style INTERP fill:#388e3c,color:#fff
style STANDALONE fill:#388e3c,color:#fff
```
### Key modules
`venv.py` is the core abstraction. `Venv` wraps a single virtual environment (create, install, uninstall, upgrade) and
`VenvContainer` manages the collection under `PIPX_HOME/venvs/`. Both delegate pip operations to the shared libraries
venv managed by `shared_libs.py`.
`paths.py` resolves all directory locations from environment variables, platform defaults, and legacy fallback paths.
`pipx_metadata_file.py` serializes install options (spec, pip args, injected packages) to JSON inside each venv so that
`upgrade` and `reinstall` can reproduce the original install.
`interpreter.py` and `standalone_python.py` handle Python version resolution. When `--fetch-python` is `missing` or
`always`, pipx downloads a standalone build from
[python-build-standalone](https://github.com/astral-sh/python-build-standalone/releases) and caches it locally. The
`pipx interpreter` subcommands (list, prune, upgrade) manage these cached interpreters.
`commands/run.py` includes PEP 723 inline script metadata parsing. When you run a `.py` file, pipx scans for a
`# /// script` block, extracts TOML-declared dependencies, and installs them into a cached temporary venv.
## Running pipx For Development
To develop `pipx`, either create a [developer environment](#creating-a-developer-environment), or perform an editable
install:
```
python -m pip install -e .
python -m pipx --version
```
## Running Tests
### Setup
pipx uses [tox](https://pypi.org/project/tox/) for development, continuous integration testing, and various tasks.
`tox` defines environments in `tox.toml` which can be run with `tox run -e ENV_NAME`. Environment names can be listed
with `tox list`.
Install tox for pipx development:
```
python -m pip install --user tox
```
Tests are defined as `tox` environments. You can see all tox environments with
```
tox list
```
At the time of this writing, the output looks like this
```
default environments:
3.13 -> run tests with 3.13
3.12 -> run tests with 3.12
3.11 -> run tests with 3.11
3.10 -> run tests with 3.10
lint -> run pre-commit on the codebase
docs -> build documentation
man -> build man page
```
### Creating a developer environment
For developing the tool (and to attach to your IDE) we recommend creating a Python environment via `tox run -e dev`,
afterwards use the Python interpreter available under `.tox/dev/bin/python`.
### Unit Tests
To run unit tests in Python 3.12, you can run
```
tox run -e 3.12
```
> [!TIP]
> You can run a specific unit test by passing arguments to pytest, the test runner pipx uses:
>
> ```
> tox run -e 3.10 -- -k EXPRESSION
> ```
>
> `EXPRESSION` can be a test name, such as
>
> ```
> tox run -e 3.10 -- -k test_uninstall
> ```
>
> Coverage errors can usually be ignored when only running a subset of tests.
### Running Unit Tests Offline
Running the unit tests requires a directory `.pipx_tests/package_cache` to be populated from a fixed list of package
distribution files (wheels or source files). If you have network access, `tox` automatically makes sure this directory
is populated (including downloading files if necessary) as a first step. Thus, if you are running the tests with network
access, you can ignore the rest of this section.
If, however, you wish to run tests offline without the need for network access, you can populate
`.pipx_tests/package_cache` yourself manually beforehand when you do have network access.
### Lint Tests
Linting is done via `pre-commit`, setting it up and running it can be done via `tox` by typing:
```
tox run -e lint
```
### Installing or injecting new packages in tests
If the tests are modified such that a new package / version combination is `pipx install`ed or `pipx inject`ed that
wasn't used in other tests, then one must make sure it's added properly to the packages lists in
`testdata/tests_packages`.
To accomplish this:
- Edit `testdata/tests_packages/primary_packages.txt` to add the new package(s) that you wish to `pipx install` or
`pipx inject` in the tests.
Then using Github workflows to generate all platforms in the Github CI:
- Manually activate the Github workflow: Create tests package lists for offline tests
- Download the artifact `lists` and put the files from it into `testdata/tests_packages/`
Finally, check-in the new or modified list files in the directory `testdata/tests_packages`
## Testing pipx on Continuous Integration builds
Upon opening pull requests GitHub Actions will automatically trigger.
## Building Documentation
`pipx` autogenerates API documentation, and also uses templates.
When updating pipx docs, make sure you are modifying the `docs` directory.
You can generate the documentation with
```
tox run -e docs
```
This will capture CLI documentation for any pipx argument modifications, as well as generate templates to the docs
directory.
## Releasing New `pipx` Versions
The release process for pipx is designed to be simple and fully automated with a single button press. The workflow
automatically determines the next version based on changelog fragments, generates the changelog, creates the release
commit, and publishes to PyPI.
### Initiating a Release
Navigate to the **Actions** tab in the GitHub repository and select the **Pre-release** workflow. Click **Run workflow**
and choose the appropriate version bump strategy. The `auto` option intelligently determines whether a minor or patch
bump is needed by examining the types of changelog fragments present. If new features or removals exist, it performs a
minor version bump; otherwise, it increments the patch version. Alternatively, you can explicitly select `major`,
`minor`, or `patch` to control the version increment directly.
### What Happens During Release
Once triggered, the pre-release workflow executes the `scripts/release.py` script which collects all changelog fragments
from the `changelog.d/` directory and uses towncrier to generate the updated changelog. It then creates a release commit
with the message "Release {version}" and tags it with the version number. After running pre-commit hooks to ensure
formatting, both the commit and tag are pushed to the main branch.
The act of pushing a version tag (matching the pattern `*.*.*`) automatically triggers the main release workflow. This
workflow builds the project distribution files, publishes the package to PyPI using trusted publishing, creates a GitHub
release with auto-generated notes, and builds the zipapp using the minimum supported Python version before uploading it
to the GitHub release assets.
### Version Calculation Examples
Starting from version `1.8.0`, the version bump types produce the following results: `auto` with feature fragments
becomes `1.9.0`, while `auto` with only bugfixes becomes `1.8.1`. Selecting `major` explicitly jumps to `2.0.0`, `minor`
moves to `1.9.0`, and `patch` increments to `1.8.1`. This automation eliminates the need for manual version management
and ensures consistency across releases.
pipx-1.14.0/docs/explanation/ 0000775 0000000 0000000 00000000000 15210205776 0016034 5 ustar 00root root 0000000 0000000 pipx-1.14.0/docs/explanation/comparisons.md 0000664 0000000 0000000 00000035060 15210205776 0020717 0 ustar 00root root 0000000 0000000 ## pipx vs pip
- pip is a general Python package installer. It can be used to install libraries or CLI applications with entrypoints.
- pipx is a specialized package installer. It can only be used to install packages with CLI entrypoints.
- pipx and pip both install packages from PyPI (or locally)
- pipx relies on pip (and venv)
- pipx replaces a subset of pip's functionality; it lets you install CLI applications but NOT libraries that you import
in your code.
- you can install pipx with pip
Example interaction: Install pipx with pip: `pip install --user pipx`
## pipx vs uv tool
Both [`uv tool`](https://docs.astral.sh/uv/concepts/tools/) and pipx install a Python tool into its own virtual
environment and expose the tool's console scripts on `PATH`. Both have a one-shot run mode (`uvx` and `pipx run`). `uvx`
is `uv tool run`. They differ in where state lives, which extra commands they ship, and how they handle managed Python.
pipx keeps the same CLI across pip and uv backends; `pipx install pipx[uv]` opts you into uv-speed venv creation without
changing any commands. `uv tool` ships a smaller per-tool surface, then reuses the rest of `uv` for free: managed
Python, content-addressed cache, lockfiles, PEP 723 script handling.
### Where state lives
| | pipx | uv tool |
| ---------------------- | ---------------------------------------------- | ------------------------------------------ |
| Per-tool venvs | `$PIPX_HOME/venvs/` (`PIPX_HOME`) | `$UV_TOOL_DIR/` (`UV_TOOL_DIR`) |
| Exposed binaries | `$PIPX_BIN_DIR` (default `~/.local/bin`) | `$UV_TOOL_BIN_DIR` (default same) |
| Man pages | `$PIPX_MAN_DIR` (default `~/.local/share/man`) | _not exposed_ |
| Shared pip/setup/wheel | `$PIPX_HOME/shared` (pip-backend only) | _none; uv venvs ship without pip_ |
| Ephemeral run cache | `$PIPX_HOME/.cache` (TTL 14 days) | `$UV_CACHE_DIR` (no TTL; `uv cache prune`) |
| Standalone Python | `$PIPX_HOME/py` (`PIPX_FETCH_PYTHON`) | `$UV_PYTHON_INSTALL_DIR` |
| System-wide install | `--global`, `PIPX_GLOBAL_*` | _not supported_ |
`PIPX_BIN_DIR` and `UV_TOOL_BIN_DIR` both default to `~/.local/bin` on Unix, so installing the same tool with both
managers writes the same filename. Each manager refuses to overwrite a binary the other one wrote without `--force`. Use
`pipx install --suffix=...` to keep two copies side-by-side; uv has no equivalent.
### Subcommand mapping
| Task | pipx | uv tool |
| ------------------------------ | ------------------------------------------------- | ------------------------------------------------------------------- |
| Install from PyPI | `pipx install ruff` | `uv tool install ruff` (or `uvx ruff` for one-off) |
| Install from a git URL | `pipx install 'git+https://โฆ'` | `uv tool install 'git+https://โฆ'` |
| Install editable from path | `pipx install -e ./mypkg` | `uv tool install -e ./mypkg` |
| One-off run (no install) | `pipx run black .` | `uvx black .` |
| One-off run with extra dep | _no clean equivalent_ | `uvx --with mkdocs-material mkdocs` |
| Pinned-version one-off | `pipx run --spec 'ruff==0.6.0' ruff check` | `uvx ruff@0.6.0 check` |
| Add a dep to existing tool | `pipx inject mkdocs mkdocs-material` | `uv tool install mkdocs --with mkdocs-material` (rebuilds) |
| Remove an injected dep | `pipx uninject mkdocs mkdocs-material` | _rebuild without `--with`_ |
| Upgrade one | `pipx upgrade ruff` | `uv tool upgrade ruff` |
| Upgrade all | `pipx upgrade-all` | `uv tool upgrade --all` |
| List installed | `pipx list` | `uv tool list` (`--show-with`, `--outdated`, โฆ) |
| Reinstall (e.g. after Py bump) | `pipx reinstall ruff` / `reinstall-all` | `uv tool upgrade --reinstall ruff` / `--all -p 3.13` |
| Run pip inside a venv | `pipx runpip -- pip ...` | _not supported (no pip in uv venvs)_ |
| PATH setup | `pipx ensurepath` | `uv tool update-shell` |
| Show resolved env | `pipx environment` | `uv tool dir`, `uv tool dir --bin`, `uv cache dir`, `uv python dir` |
| PEP 723 inline script | `pipx run script.py` (with uv backend โ `uv run`) | `uv run --script script.py` |
### Only in pipx
- `pipx inject` / `uninject` add or remove a package in place. `uv tool install --with` reaches the same end state by
rebuilding the venv.
- `pipx runpip -- ...` runs pip inside a tool's venv. uv venvs have no pip.
- `--include-deps` exposes entry points from every dependency. uv requires you to enumerate dep packages with
`--with-executables-from`.
- `--suffix` keeps two copies of the same tool side-by-side.
- `--global` and the `PIPX_GLOBAL_*` variables drive a system-wide install.
- Manual pages get symlinked under `$PIPX_MAN_DIR`.
- `pipx install-all ` rebuilds every venv from a `pipx list --json` snapshot for cross-machine migration.
- `[project.entry-points."pipx.run"]` declares pipx-specific runtime extras in the package metadata.
- `pipx environment` prints every variable and its resolved value in one place.
### Only in uv tool
- `uv tool list --outdated` queries newer versions without upgrading.
- `uv tool list` toggles columns via `--show-with`, `--show-paths`, `--show-version-specifiers`, `--show-extras`,
`--show-python`.
- `uvx --with-editable PATH` adds editable extras for a one-off run.
- `uv tool upgrade --all -p 3.13` re-pins every tool to a different Python in one shot.
- `uv python install/list/find/pin/upgrade/uninstall` integrates managed Python; uv auto-fetches when the requested
Python isn't installed.
- `--exclude-newer`, `--torch-backend`, and `--isolated` add reproducibility knobs that pipx forwards but doesn't add on
its own.
- The content-addressed cache spans `uv pip`, `uv tool`, `uv run`, and `uv venv`. Wheels downloaded once get reused
everywhere.
### Gotchas
- `uvx` reuses cached envs across invocations until you prune the cache (`uv cache clean`), pin a new version
(`uvx black@latest`), or pass `--refresh`. `pipx run` also caches, but the temp venv expires after 14 days idle.
- `uvx` prefers a persistent install when one exists. After `uv tool install ruff`, plain `uvx ruff` reuses that env
instead of building an ephemeral one. Pass `--isolated` to bypass.
- `uv tool` ignores project-local `.python-version` files. `uv run` honors them; tool envs do not. pipx never reads
them; pass `--python` or set `PIPX_DEFAULT_PYTHON`.
- `uv python upgrade` only bumps patch versions. To move a tool from 3.12 to 3.13 run `uv tool upgrade --all -p 3.13`.
pipx's equivalent is `reinstall-all --python python3.13`.
- `uv run --script` needs a real on-disk path. When `pipx run script.py` content arrives via URL or named pipe, the uv
backend falls back to building a venv.
### Picking one
Pipx wins when you need its tool-specific extras: `inject`/`uninject`, `--global`, `--suffix`, manual pages, or
`pipx install-all` for migration. Install `pipx[uv]` to keep that surface and pick up uv-speed venv creation. Reach for
`uv tool` when you already drive uv for managed Python or `uv run --script` and want one binary for everything. Running
both is fine; the only collision point is the shared bin dir, and both sides refuse to overwrite without `--force`.
## pipx vs poetry and pipenv
- pipx is used solely for application consumption: you install CLI apps with it
- pipenv and poetry are CLI apps used to develop applications and libraries
- all three tools wrap pip and virtual environments for more convenient workflows
Example interaction: Install pipenv and poetry with pipx: `pipx install poetry` Run pipenv or poetry with pipx:
`pipx run poetry --help`
## pipx vs venv
- venv is part of Python's standard library in Python 3.2 and above
- venv creates "virtual environments" which are sandboxed python installations
- pipx heavily relies on the venv package
Example interaction: pipx installs packages to environments created with venv. `pipx install black --verbose`
## pipx vs pyenv
- pyenv manages python versions on your system. It helps you install versions like Python 3.6, 3.7, etc.
- pipx installs packages in virtual environments and exposes their entrypoints on your PATH
Example interaction: Install a Python interpreter with pyenv, then install a package using pipx and that new
interpreter: `pipx install black --python=python3.11` where python3.11 was installed on the system with pyenv
## pipx vs pipsi
- pipx and pipsi both install packages in a similar way
- pipx is under active development. pipsi is no longer maintained.
- pipx always makes sure you're using the latest version of pip
- pipx has the ability to run an app in one line, leaving your system unchanged after it finishes (`pipx run APP`) where
pipsi does not
- pipx has the ability to recursively install binaries from dependent packages
- pipx adds more useful information to its output
- pipx has more CLI options such as upgrade-all, reinstall-all, uninstall-all
- pipx is more modern. It uses Python 3.6+, and the `venv` package in the Python3 standard library instead of the python
2 package `virtualenv`.
- pipx works with Python homebrew installations while pipsi does not (at least on my machine)
- pipx defaults to less verbose output
- pipx allows you to see each command it runs by passing the --verbose flag
- pipx prints emojis ๐
Example interaction: None. Either one or the other should be used. These tools compete for a similar workflow.
### Migrating to pipx from pipsi
After you have installed pipx, run
[migrate_pipsi_to_pipx.py](https://raw.githubusercontent.com/pypa/pipx/main/scripts/migrate_pipsi_to_pipx.py). Why not
do this with your new pipx installation?
```
pipx run https://raw.githubusercontent.com/pypa/pipx/main/scripts/migrate_pipsi_to_pipx.py
```
## pipx vs brew
- Both brew and pipx install cli tools
- They install them from different sources. brew uses a curated repository specifically for brew, and pipx generally
uses PyPI.
Example interaction: brew can be used to install pipx, but they generally don't interact much.
## pipx vs npx
- Both can run cli tools (npx will search for them in node_modules, and if not found run in a temporary environment.
`pipx run` will search in `__pypackages__` and if not found run in a temporary environment)
- npx works with JavaScript and pipx works with Python
- Both tools attempt to make running executables written in a dynamic language (JS/Python) as easy as possible
- pipx can also install tools globally; npx cannot
Example interaction: None. These tools work for different languages.
## pipx vs pip-run
[pip-run](https://github.com/jaraco/pip-run) is focused on running **arbitrary Python code in ephemeral environments**
while pipx is focused on running **Python binaries in ephemeral and non-ephemeral environments**.
For example these two commands both install poetry to an ephemeral environment and invoke poetry with `--help`.
```
pipx run poetry --help
pip-run poetry -- -m poetry --help
```
Example interaction: None.
## pipx vs fades
[fades](https://github.com/PyAr/fades) is a tool to run **individual** Python scripts inside automatically provisioned
virtualenvs with their dependencies installed.
- Both [fades](https://github.com/PyAr/fades#how-to-mark-the-dependencies-to-be-installed) and
[pipx run](../reference/examples.md#pipx-run-examples) allow specifying a script's dependencies in specially
formatted comments, but the exact syntax differs. (pipx's syntax is standardized by a
[provisional specification](https://packaging.python.org/en/latest/specifications/inline-script-metadata/), fades's
syntax is not standardized.)
- Both tools automatically set up reusable virtualenvs containing the necessary dependencies.
- Both can download Python scripts/packages to execute from remote resources.
- fades can only run individual script files while pipx can also run packages.
Example interaction: None.
## pipx vs pae/pactivate
_pae_ is a Bash command-line function distributed with [pactivate](https://github.com/cynic-net/pactivate) that uses
pactivate to create non-ephemeral environments focused on general use, rather than just running command-line
applications.
There is [a very detailed comparison here](https://github.com/cynic-net/pactivate/blob/main/doc/vs-pipx.md), but to
briefly summarize:
Similarities:
- Both create isolated environments without having to specify (and remember) a directory in which to store them.
- Both allow you to use any Python interpreter available on your system (subject to version restrictions below).
pae advantages:
- Supports all versions of Python from 2.7 upward. pipx requires โฅ3.10.
- Fewer dependencies. (See the detailed comparison for more information.)
- Easier to have multiple versions of a single program and/or use different Python versions for a single program.
- Somewhat more convenient for running arbitrary command-line programs in virtual environments, installing multiple
packages in a single environment, and activating virtual environments.
- Integrates well with source code repos using [pactivate](https://github.com/cynic-net/pactivate).
pae disadvantages:
- Usable with Bash shell only.
- Slightly less quick and convenient for installing/running command-line programs from single Python packages.
- Can be slower than pipx at creating virtual environments.
Example interaction: None. Either one or the other should be used. These tools compete for a similar workflow.
pipx-1.14.0/docs/explanation/how-pipx-works.md 0000664 0000000 0000000 00000011240 15210205776 0021272 0 ustar 00root root 0000000 0000000 ## How it Works
### `pipx install`
When installing a package and its binaries on Linux (`pipx install package`), pipx first creates or reuses a shared
virtual environment at `~/.local/share/pipx/shared/` that contains the packaging library `pip`, ensuring it is updated
to its latest version. It then creates an isolated virtual environment at `~/.local/share/pipx/venvs/PACKAGE` that uses
the shared pip via a [.pth file](https://docs.python.org/3/library/site.html) and installs the desired package into it.
Once the package is installed, pipx exposes its console scripts and GUI scripts by symlinking them into `~/.local/bin`
(for example, `~/.local/bin/black` -> `~/.local/share/pipx/venvs/black/bin/black`). It also symlinks any manual pages
into `~/.local/share/man/man[1-9]`. As long as `~/.local/bin/` is on your `PATH`, the new commands are available
globally, and on systems with `man` support the pages are accessible too.
Adding the `--global` flag to any `pipx` command executes the action in global scope, exposing the app to all system
users. See the [configuration reference](../how-to/configure-paths.md#-global-argument) for details. Note that this is
not available on Windows.
```mermaid
flowchart LR
A["pipx install black"] --> B["shared venv (pip)"]
B --> C["create venv ~/.local/share/pipx/ venvs/black/"]
C --> D["pip install black"]
D --> E["symlink binaries ~/.local/bin/black"]
D --> F["symlink man pages ~/.local/share/man/"]
style A fill:#3f72af,color:#fff
style B fill:#2a9d8f,color:#fff
style C fill:#2a9d8f,color:#fff
style D fill:#2a9d8f,color:#fff
style E fill:#388e3c,color:#fff
style F fill:#388e3c,color:#fff
```
### `pipx run`
`pipx run BINARY` reuses the same shared pip environment, then either reuses a cached virtual environment or creates a
new temporary one. The cache key is a hash of the package name, spec, python version, and pip arguments. pipx creates a
virtual environment with `python -m venv`, installs the package, and invokes the binary.
Cached environments expire after a few days. On next run, pipx fetches the latest version.
```mermaid
flowchart LR
A["pipx run pycowsay"] --> B["shared venv (pip)"]
B --> C{"cached venv?"}
C -- "yes" --> E["reuse cached venv"]
C -- "no" --> D["create temp venv pip install pycowsay"]
D --> F["invoke binary"]
E --> F
style A fill:#3f72af,color:#fff
style B fill:#2a9d8f,color:#fff
style C fill:#c78c20,color:#fff
style D fill:#2a9d8f,color:#fff
style E fill:#2a9d8f,color:#fff
style F fill:#388e3c,color:#fff
```
### Directory layout
The overall directory structure that pipx manages looks like this:
```mermaid
flowchart TD
HOME["~"] --> BIN["~/.local/bin/ (on PATH)"]
HOME --> DATA["~/.local/share/pipx/"]
DATA --> SHARED["shared/ (pip, setuptools)"]
DATA --> VENVS["venvs/"]
VENVS --> V1["black/"]
VENVS --> V2["poetry/"]
VENVS --> V3["ruff/"]
V1 --> V1BIN["bin/black"]
BIN --> |"symlink"| V1BIN
style HOME fill:#3f72af,color:#fff
style BIN fill:#388e3c,color:#fff
style DATA fill:#2a9d8f,color:#fff
style SHARED fill:#c78c20,color:#fff
style VENVS fill:#2a9d8f,color:#fff
style V1 fill:#7c4dff,color:#fff
style V2 fill:#7c4dff,color:#fff
style V3 fill:#7c4dff,color:#fff
style V1BIN fill:#7c4dff,color:#fff
```
You can do all of this yourself. pipx automates it. Pass `--verbose` to see every command and argument pipx runs.
### Resolving the Python interpreter
When you pass `--python `, pipx walks a fixed search order:
1. Treat the argument as a literal path; use it when the file exists.
1. Call `shutil.which()` to find a matching command on `PATH`.
1. On non-Windows, try `python` derived from the version string.
1. If `py` is available (Windows), ask the launcher for that version.
Only after every step fails does pipx consider downloading a build from
[python-build-standalone](https://github.com/astral-sh/python-build-standalone). The `--fetch-python` flag (or
`PIPX_FETCH_PYTHON`) decides when that download is allowed:
- `never` (the default) keeps pipx local: the search above must succeed or pipx errors out.
- `missing` falls back to a download when every step above fails.
- `always` skips the search and uses a fresh standalone build for the requested version.
Use `always` when the system Python is patched in ways that break installed applications. Some distros strip optional
modules (`tkinter`, `lzma`), change the site-packages layout, or backport behaviour changes; a found system Python is
worse than no Python at all. Otherwise, use `missing` so pipx reuses what the system already provides.
pipx-1.14.0/docs/explanation/index.md 0000664 0000000 0000000 00000000674 15210205776 0017474 0 ustar 00root root 0000000 0000000 # Explanation
Design rationale and background knowledge. Read these to understand *why* pipx works the way it does.
- [How pipx Works](how-pipx-works.md) โ virtual environment architecture and the shared pip library.
- [Comparisons](comparisons.md) โ how pipx relates to pip, poetry, pipenv, pyenv, brew, npx, and more.
- [Making Packages Compatible](making-packages-compatible.md) โ adding entry points and man pages for pipx support.
pipx-1.14.0/docs/explanation/making-packages-compatible.md 0000664 0000000 0000000 00000010577 15210205776 0023527 0 ustar 00root root 0000000 0000000 ## Developing for pipx
If you are a developer and want to be able to run
```
pipx install MY_PACKAGE
```
make sure you include `scripts` in your main table[^1] in `pyproject.toml` or its legacy equivalents for `setup.cfg` and
`setup.py`. pipx also exposes `gui-scripts` entry points, which are useful for GUI applications on Windows (they launch
without opening a console window).
=== "pyproject.toml"
```ini
[project.scripts]
foo = "my_package.some_module:main_func"
bar = "other_module:some_func"
[project.gui-scripts]
baz = "my_package_gui:start_func"
```
=== "setup.cfg"
```ini
[options.entry_points]
console_scripts =
foo = my_package.some_module:main_func
bar = other_module:some_func
gui_scripts =
baz = my_package_gui:start_func
```
=== "setup.py"
```python
setup(
# other arguments here...
entry_points={
'console_scripts': [
'foo = my_package.some_module:main_func',
'bar = other_module:some_func',
],
'gui_scripts': [
'baz = my_package_gui:start_func',
]
},
)
```
In this case `foo` and `bar` (and `baz` on Windows) would be available as "applications" to pipx after installing the
above example package, invoking their corresponding entry point functions.
```mermaid
flowchart LR
TOML["pyproject.toml [project.scripts]"] --> |"defines"| EP["entry points foo, bar"]
EP --> |"pipx install"| VENV["isolated venv"]
VENV --> |"symlinks"| BIN["~/.local/bin/ foo, bar"]
BIN --> |"invokes"| FUNC["my_package: main_func()"]
style TOML fill:#3f72af,color:#fff
style EP fill:#2a9d8f,color:#fff
style VENV fill:#7c4dff,color:#fff
style BIN fill:#388e3c,color:#fff
style FUNC fill:#c78c20,color:#fff
```
### The `pipx.run` entry point group
When a user runs `pipx run PACKAGE`, pipx looks for a console script matching the package name. If the package name and
script name differ, the user has to write `pipx run --spec PACKAGE SCRIPT`, which is less convenient.
Package authors can declare a `pipx.run` entry point group to tell pipx which function to invoke for `pipx run`. This
entry point takes priority over console scripts when present.
=== "pyproject.toml"
```toml
[project.entry-points."pipx.run"]
my-package = "my_package.cli:main"
```
=== "setup.cfg"
```ini
[options.entry_points]
pipx.run =
my-package = my_package.cli:main
```
With this declaration, `pipx run my-package` invokes `my_package.cli:main` even if no console script named `my-package`
exists. The [build](https://github.com/pypa/build) package uses this pattern so that `pipx run build` works even though
build's console script is named `pyproject-build`.
### Manual pages
If you wish to provide documentation via `man` pages on UNIX-like systems then these can be added as data files:
=== "setuptools"
```toml title="pyproject.toml"
[tool.setuptools.data-files]
"share/man/man1" = [
"manpage.1",
]
```
```ini title="setup.cfg"
[options.data_files]
share/man/man1 =
manpage.1
```
```python title="setup.py"
setup(
# other arguments here...
data_files=[('share/man/man1', ['manpage.1'])]
)
```
> [!WARNING]
> The `data-files` keyword is "discouraged" in the
> [setuptools documentation](https://setuptools.pypa.io/en/latest/userguide/pyproject_config.html#setuptools-specific-configuration)
> but there is no alternative if `man` pages are a requirement.
=== "pdm-backend"
```toml title="pyproject.toml"
[tool.pdm.build]
source-includes = ["share"]
[tool.pdm.build.wheel-data]
data = [
{ path = "share/man/man1/*", relative-to = "." },
]
```
In this case the manual page `manpage.1` could be accessed by the user after installing the above example package.
For a real-world example, see [pycowsay](https://github.com/cs01/pycowsay/blob/master/setup.py)'s `setup.py` source
code.
You can read more about entry points
[here](https://setuptools.pypa.io/en/latest/userguide/quickstart.html#entry-points-and-automatic-script-creation).
[^1]: This is often the `[project]` table, but might also be differently named. Read more in the
[PyPUG](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#writing-your-pyproject-toml).
pipx-1.14.0/docs/how-to/ 0000775 0000000 0000000 00000000000 15210205776 0014727 5 ustar 00root root 0000000 0000000 pipx-1.14.0/docs/how-to/configure-paths.md 0000664 0000000 0000000 00000012212 15210205776 0020345 0 ustar 00root root 0000000 0000000 ## Installation Options
The default binary location for pipx-installed apps is `~/.local/bin`. This can be overridden with the environment
variable `PIPX_BIN_DIR`. The default manual page location for pipx-installed apps is `~/.local/share/man`. This can be
overridden with the environment variable `PIPX_MAN_DIR`. If the `--global` option is used, the default locations are
`/usr/local/bin` and `/usr/local/share/man` respectively and can be overridden with `PIPX_GLOBAL_BIN_DIR` and
`PIPX_GLOBAL_MAN_DIR`.
pipx's default virtual environment location is typically `~/.local/share/pipx` on Linux/Unix, `~/.local/pipx` on macOS
and `~\pipx` on Windows. For compatibility reasons, if `~/.local/pipx` on Linux, `%USERPROFILE%\AppData\Local\pipx` or
`~\.local\pipx` on Windows or `~/Library/Application Support/pipx` on macOS exists, it will be used as the default
location instead. This can be overridden with the `PIPX_HOME` environment variable. If the `--global` option is used,
the default location is always `/opt/pipx` and can be overridden with `PIPX_GLOBAL_HOME`.
In case one of these fallback locations exist, we recommend either manually moving the pipx files to the new default
location (see the [Moving your pipx installation](move-installation.md) section of the docs), or setting the `PIPX_HOME`
environment variable (discarding files existing in the fallback location).
As an example, you can install global apps accessible by all users on your system with either of the following commands
(on MacOS, Linux, and Windows WSL):
```
sudo PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin PIPX_MAN_DIR=/usr/local/share/man pipx install
# or shorter (with pipx>=1.5.0)
sudo pipx install --global
```
> [!NOTE]
> After version 1.2.0, the default pipx paths have been moved from `~/.local/pipx` to specific user data directories on
> each platform using [platformdirs](https://pypi.org/project/platformdirs/) library
>
> | Old Path | New Path |
> | ---------------------- | ------------------------------------------ |
> | `~/.local/pipx/.trash` | `platformdirs.user_data_dir()/pipx/trash` |
> | `~/.local/pipx/shared` | `platformdirs.user_data_dir()/pipx/shared` |
> | `~/.local/pipx/venvs` | `platformdirs.user_data_dir()/pipx/venvs` |
> | `~/.local/pipx/.cache` | `platformdirs.user_cache_dir()/pipx` |
> | `~/.local/pipx/logs` | `platformdirs.user_log_dir()/pipx/log` |
>
> `user_data_dir()`, `user_cache_dir()` and `user_log_dir()` resolve to appropriate platform-specific user data, cache
> and log directories. See the
> [platformdirs documentation](https://platformdirs.readthedocs.io/en/latest/api.html#platforms) for details.
>
> This was reverted in 1.5.0 for Windows and macOS. We heavily recommend not using these locations on Windows and macOS
> anymore, due to multiple incompatibilities discovered with these locations, documented
> [here](troubleshoot.md#why-are-spaces-in-the-pipx_home-path-bad).
### Customising your installation
#### `--global` argument
The `--global` flag installs applications into a system-wide location accessible to all users. It must be placed
**after** the subcommand, not before it:
```
# correct
sudo pipx install --global pycowsay
sudo pipx list --global
# wrong (--global is silently ignored when placed before the subcommand)
sudo pipx --global install pycowsay
```
Default global paths are `/usr/local/bin` for binaries, `/usr/local/share/man` for man pages, and `/opt/pipx` for
virtual environments. Override them with `PIPX_GLOBAL_BIN_DIR`, `PIPX_GLOBAL_MAN_DIR`, and `PIPX_GLOBAL_HOME`. Run
`sudo pipx ensurepath --global` to add the global binary directory to the system `PATH`.
The `--global` flag is not supported on Windows.
#### `--prepend` argument
The `--prepend` argument can be passed to the `pipx ensurepath` command to prepend the `pipx` bin directory to the
user's PATH environment variable instead of appending to it. This can be useful if you want to prioritise
`pipx`-installed binaries over system-installed binaries of the same name.
### Configuring pip for pipx
pipx uses pip internally for all package installs, including its own shared libraries (pip, setuptools). To point pip at
a private index or pass custom options, set `PIP_*` environment variables. pipx forwards them to every pip invocation.
For example, to use a private package index:
```
export PIP_INDEX_URL=https://my-private-index.example.com/simple/
export PIP_TRUSTED_HOST=my-private-index.example.com
pipx install my-private-package
```
These variables also apply when pipx upgrades its shared libraries (`pipx upgrade-shared`). You can set them permanently
in your shell profile or in pip's own config file (`pip.conf` / `pip.ini`). See the
[pip configuration documentation](https://pip.pypa.io/en/stable/topics/configuration/) for details.
Set `PIPX_DISABLE_SHARED_LIBS_AUTO_UPGRADE=1` to skip automatic shared library upgrades during commands such as
`pipx install` and `pipx upgrade`. The explicit `pipx upgrade-shared` command still upgrades the shared libraries.
Per-command pip options can be passed with `--pip-args`:
```
pipx install my-package --pip-args='--no-cache-dir --trusted-host=my-host'
```
pipx-1.14.0/docs/how-to/index.md 0000664 0000000 0000000 00000002071 15210205776 0016360 0 ustar 00root root 0000000 0000000 # How-to Guides
Recipes for common pipx tasks. Each guide covers a specific goal and assumes you have pipx installed.
- [Install pipx](install-pipx.md) โ system requirements and OS-specific installation steps.
- [Upgrade pipx](upgrade-pipx.md) โ keep pipx itself up to date.
- [Inject Packages](inject-packages.md) โ add extra packages into an existing pipx environment.
- [Pin Packages](pin-packages.md) โ hold a package at its current version.
- [Run Scripts](run-scripts.md) โ run specific versions, from URLs, or from source control.
- [Standalone Python](standalone-python.md) โ install with a downloaded Python build instead of the system one.
- [Use with pre-commit](use-with-pre-commit.md) โ integrate pipx with pre-commit hooks.
- [Configure Paths](configure-paths.md) โ customise `PIPX_HOME`, `PIPX_BIN_DIR`, and global installs.
- [Move Installation](move-installation.md) โ relocate your pipx directory.
- [Shell Completions](shell-completions.md) โ enable tab completion for your shell.
- [Troubleshoot](troubleshoot.md) โ fix common problems.
pipx-1.14.0/docs/how-to/inject-packages.md 0000664 0000000 0000000 00000002256 15210205776 0020306 0 ustar 00root root 0000000 0000000 ## Inject a package
`pipx inject` adds extra packages into an existing pipx-managed virtual environment. If you have `ipython` installed and
want `matplotlib` available inside it:
```
pipx inject ipython matplotlib
```
Inject multiple packages at once, from a requirements file, or both:
```
pipx inject ipython matplotlib pandas
pipx inject ipython -r useful-packages.txt
pipx inject ipython extra-pkg -r more-packages.txt
```
### Expose injected apps
By default, injected packages do not add their entry points to your `PATH`. Use `--include-apps` to expose them:
```
pipx inject ipython black --include-apps
```
`--include-deps` exposes entry points from the injected package's dependencies too (implies `--include-apps`).
### Other flags
- `--force` / `-f` reinstalls the package even if it is already injected.
- `--editable` / `-e` installs the package in editable (development) mode.
- `--with-suffix SUFFIX` targets a suffixed venv (e.g. `ipython_3.11`).
- `--pip-args` passes extra arguments to pip (e.g. `--pip-args='--no-cache-dir'`).
- `--index-url` / `-i` sets the PyPI index URL for this inject.
- `--system-site-packages` gives the venv access to the system site-packages.
pipx-1.14.0/docs/how-to/install-pipx.md 0000664 0000000 0000000 00000014116 15210205776 0017700 0 ustar 00root root 0000000 0000000 ## System Requirements
python 3.10+ is required to install pipx. pipx can run binaries from packages with Python 3.3+. Don't have Python 3.10
or later? See [Python 3 Installation & Setup Guide](https://realpython.com/installing-python/).
You also need to have `pip` installed on your machine for `python3`. The installation process varies from system to
system. Consult [pip's installation instructions](https://pip.pypa.io/en/stable/installing/). Installing on Linux works
best with a
[Linux Package Manager](https://packaging.python.org/guides/installing-using-linux-tools/#installing-pip-setuptools-wheel-with-linux-package-managers).
pipx works on macOS, Linux, and Windows.
[](https://repology.org/metapackage/pipx/versions)
## Installing pipx
### On macOS:
```
brew install pipx
pipx ensurepath
```
#### Additional (optional) commands
To allow pipx actions in global scope (requires pipx 1.5.0+):
```
sudo pipx ensurepath --global
```
To prepend the pipx bin directory to PATH instead of appending it (requires pipx 1.7.0+):
```
sudo pipx ensurepath --prepend
```
> [!NOTE]
> Some distributions ship older pipx versions (e.g. Ubuntu 24.04 ships v1.4.3). If `--global` or `--prepend` fails with
> "unrecognized arguments", upgrade pipx first: `pip install --user --upgrade pipx`, or install a newer version from a
> different source.
For more details, refer to [Customising your installation](configure-paths.md).
### On Linux:
- Ubuntu 23.04 or above
```
sudo apt update
sudo apt install pipx
pipx ensurepath
```
- Fedora:
```
sudo dnf install pipx
pipx ensurepath
```
- Using `pip` on other distributions:
```
python3 -m pip install --user pipx
python3 -m pipx ensurepath
```
> [!NOTE]
> Distributions that adopt [PEP 668](https://peps.python.org/pep-0668/) (Ubuntu 23.04+, Debian 12+, Fedora 38+) mark the
> system Python as externally managed. Running `pip install --user` on these systems fails with an
> `externally-managed-environment` error. Use your distribution's package manager (`apt install pipx`,
> `dnf install pipx`) instead. If no distro package exists, install pipx inside its own virtual environment:
>
> ```
> python3 -m venv ~/.local/share/pipx-venv
> ~/.local/share/pipx-venv/bin/pip install pipx
> ln -s ~/.local/share/pipx-venv/bin/pipx ~/.local/bin/pipx
> pipx ensurepath
> ```
#### Additional (optional) commands
To allow pipx actions in global scope (requires pipx 1.5.0+):
```
sudo pipx ensurepath --global
```
To prepend the pipx bin directory to PATH instead of appending it (requires pipx 1.7.0+):
```
sudo pipx ensurepath --prepend
```
For more details, refer to [Customising your installation](configure-paths.md).
> [!NOTE]
> If you installed pipx with `pip install --user`, the `pipx` binary lives in your user directory (e.g.
> `~/.local/bin/pipx`). Running `sudo pipx` will fail because root's `PATH` does not include your user bin directory.
> Use the full path instead: `sudo ~/.local/bin/pipx ensurepath --global`. Alternatively, install pipx system-wide with
> `sudo pip install pipx` (without `--user`) or use your distribution's package manager.
### On Windows:
- Install via [Scoop](https://scoop.sh/):
```
scoop install pipx
pipx ensurepath
```
- 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 `\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.
### On FreeBSD:
- Install via package manager
```sh
pkg install -y py311-pipx
```
- Install via pip
```sh
pip install --user pipx
pipx ensurepath
```
### Using pipx without installing (via zipapp)
The zipapp can be downloaded from [Github releases](https://github.com/pypa/pipx/releases) and you can invoke it with a
Python 3.10+ interpreter:
```
python pipx.pyz ensurepath
```
### Self-managed pipx
You can use pipx to manage its own installation. This keeps pipx up to date through `pipx upgrade pipx` and avoids
relying on distro packages that may ship older versions. Bootstrap it with a temporary virtual environment:
```
python3 -m venv /tmp/bootstrap
/tmp/bootstrap/bin/pip install pipx
/tmp/bootstrap/bin/pipx install pipx
/tmp/bootstrap/bin/pipx ensurepath
rm -rf /tmp/bootstrap
```
After this, `pipx upgrade pipx` upgrades pipx like any other pipx-managed application. On Windows, pipx cannot delete
its own running executable, so it moves locked files to a trash directory and cleans them up on the next run.
## Installing packages from source control
pipx accepts any source pip supports, including git repositories. Using `black` as an example:
```
pipx install git+https://github.com/psf/black.git
pipx install git+ssh://git@github.com/psf/black # using ssh
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
```
Use pip's `egg` syntax when installing extras:
```
pipx install "git+https://github.com/psf/black.git#egg=black[jupyter]"
```
### Installing from a pull request
To test a package from an open pull request, find the fork owner and branch name on the PR page, then build the git URL.
For example, PR #794 from user `contributor` on branch `fix-something`:
```
pipx install git+https://github.com/contributor/pipx.git@fix-something
```
If the PR branch has been merged, use the merge commit hash instead:
```
pipx install git+https://github.com/pypa/pipx.git@abc123def
```
pipx-1.14.0/docs/how-to/move-installation.md 0000664 0000000 0000000 00000003767 15210205776 0020733 0 ustar 00root root 0000000 0000000 ## Moving your pipx installation
The below code snippets show how to move your pipx installation to a new directory. As an example, they move from a
non-default location to the current default locations. If you wish to move to a different location, just replace the
`NEW_LOCATION` value.
### MacOS
Current default location: `~/.local`
```bash
NEW_LOCATION=~/.local
cache_dir=$(pipx environment --value PIPX_VENV_CACHEDIR)
logs_dir=$(pipx environment --value PIPX_LOG_DIR)
trash_dir=$(pipx environment --value PIPX_TRASH_DIR)
home_dir=$(pipx environment --value PIPX_HOME)
rm -rf "$cache_dir" "$logs_dir" "$trash_dir"
mkdir -p $NEW_LOCATION && mv "$home_dir" $NEW_LOCATION
pipx reinstall-all
```
### Linux
Current default location: `~/.local/share`
```bash
cache_dir=$(pipx environment --value PIPX_VENV_CACHEDIR)
logs_dir=$(pipx environment --value PIPX_LOG_DIR)
trash_dir=$(pipx environment --value PIPX_TRASH_DIR)
home_dir=$(pipx environment --value PIPX_HOME)
# If you wish another location, replace the expression below
# and set `NEW_LOCATION` explicitly
NEW_LOCATION="${XDG_DATA_HOME:-$HOME/.local/share}"
rm -rf "$cache_dir" "$logs_dir" "$trash_dir"
mkdir -p $NEW_LOCATION && mv "$home_dir" $NEW_LOCATION
pipx reinstall-all
```
### Windows
Current default location: `~/pipx`
```powershell
$NEW_LOCATION = Join-Path "$HOME" 'pipx'
$cache_dir = pipx environment --value PIPX_VENV_CACHEDIR
$logs_dir = pipx environment --value PIPX_LOG_DIR
$trash_dir = pipx environment --value PIPX_TRASH_DIR
$home_dir = pipx environment --value PIPX_HOME
Remove-Item -Recurse -Force -ErrorAction SilentlyContinue "$cache_dir", "$logs_dir", "$trash_dir"
# Remove the destination directory to ensure rename behavior of `Move-Item`
Remove-Item -Recurse -Force -ErrorAction SilentlyContinue "$NEW_LOCATION"
Move-Item -Path $home_dir -Destination "$NEW_LOCATION"
pipx reinstall-all
```
If you would prefer doing it in bash via git-bash/WSL, feel free to use the MacOS/Linux instructions, changing the
`$NEW_LOCATION` to the Windows version.
pipx-1.14.0/docs/how-to/pin-packages.md 0000664 0000000 0000000 00000002175 15210205776 0017620 0 ustar 00root root 0000000 0000000 ## Pin installed packages
Use `pipx pin` when you need to hold an installation at its current version. Pinned packages are skipped by
`pipx upgrade`, `pipx upgrade-all`, and `pipx reinstall`, so the environment keeps its existing app and dependency
versions until you unpin it.
- `pipx pin PACKAGE` โ pins the main package and any injected packages in that virtual environment.
- `pipx pin PACKAGE --injected-only` โ leaves the main package upgradable but pins every injected package instead.
- `pipx pin PACKAGE --skip PKG_A PKG_B` โ pins injected packages except the ones you list (the flag implies
`--injected-only`).
- `pipx unpin PACKAGE` โ re-enables upgrades for the package and anything that was pinned with it.
- `pipx list --pinned` โ shows every pinned environment; add `--include-injected` to see pinned injected packages.
pipx tracks the main package and any injected packages. It does not record individual transitive dependencies, so there
is no way to pin a single dependency in isolation. Pinning the main package protects its dependency set because pipx
skips running `pip install --upgrade` for that environment.
pipx-1.14.0/docs/how-to/run-scripts.md 0000664 0000000 0000000 00000003633 15210205776 0017547 0 ustar 00root root 0000000 0000000 ## Running a specific version of a package
The `PACKAGE` argument is a
[requirement specifier](https://packaging.python.org/en/latest/glossary/#term-Requirement-Specifier), so you can pin
versions, ranges, or extras:
```
pipx run mpremote==1.20.0
pipx run --spec esptool==4.6.2 esptool.py
pipx run --spec 'esptool>=4.5' esptool.py
```
Requirement specifiers containing `>`, `<`, or spaces need quoting.
## Running with extra dependencies
`--with` adds packages to the temporary environment alongside the main app:
```
pipx run --with requests --with rich my-script.py
```
## Running from source control
`pipx run` accepts git URLs through `--spec`. Using `black` as an example:
```
pipx run --spec git+https://github.com/psf/black.git black
pipx run --spec git+ssh://git@github.com/psf/black black
pipx run --spec git+https://github.com/psf/black.git@branch black
pipx run --spec git+https://github.com/psf/black.git@ce14fa8b497bae2b50ec48b3bd7022573a59cdb1 black
pipx run --spec https://github.com/psf/black/archive/18.9b0.zip black
```
## Running from URL
You can run `.py` files hosted anywhere:
```
pipx run https://gist.githubusercontent.com/cs01/fa721a17a326e551ede048c5088f9e0f/raw/6bdfbb6e9c1132b1c38fdd2f195d4a24c540c324/pipx-demo.py
```
## Running scripts with dependencies (PEP 723)
Scripts can declare their own dependencies using
[inline script metadata](https://packaging.python.org/en/latest/specifications/inline-script-metadata/). pipx reads the
`# /// script` block and installs the listed packages before running:
```python
# test.py
# /// script
# dependencies = ["requests"]
# ///
import sys
import requests
project = sys.argv[1]
data = requests.get(f"https://pypi.org/pypi/{project}/json").json()
print(data["info"]["version"])
```
```
> pipx run test.py pipx
1.9.0
```
pipx creates a cached virtual environment keyed to the script's dependency list. Changing the dependencies creates a
fresh environment.
pipx-1.14.0/docs/how-to/shell-completions.md 0000664 0000000 0000000 00000000234 15210205776 0020711 0 ustar 00root root 0000000 0000000 ## Shell Completion
You can easily get your shell's tab completions working by following instructions printed with this command:
```
pipx completions
```
pipx-1.14.0/docs/how-to/standalone-python.md 0000664 0000000 0000000 00000004217 15210205776 0020724 0 ustar 00root root 0000000 0000000 ## Use a Standalone Python Build
pipx can install applications under a Python interpreter downloaded from
[python-build-standalone](https://github.com/astral-sh/python-build-standalone) instead of the system Python. Reach for
this when the system Python is missing the version you asked for, or when the distro patched its Python in ways that
break the application.
### Choosing when to download
Set `--fetch-python` (or `PIPX_FETCH_PYTHON`) to one of three values:
| Value | Behaviour |
| --------- | ---------------------------------------------------------------------------------- |
| `never` | Default. Don't download. Use Python interpreters from `PATH` or the `py` launcher. |
| `missing` | Look for the requested version locally first; download it when it isn't there. |
| `always` | Skip the local search and use a standalone build for the requested version. |
```
# Download only when the requested version is missing locally
pipx install --python 3.13 --fetch-python=missing my-package
# Use a fresh standalone build, ignoring system Python
pipx install --python 3.13 --fetch-python=always my-package
# Set the policy for your shell session
export PIPX_FETCH_PYTHON=missing
pipx install --python 3.13 my-package
```
pipx unpacks the interpreter into its standalone cache. Manage cached interpreters with `pipx interpreter list`,
`pipx interpreter prune`, and `pipx interpreter upgrade` (see the [reference](../reference/examples.md)).
### When `--fetch-python=always` is the right choice
- CI runs where you don't want to depend on the runner's preinstalled Python.
- Distros that strip optional modules (`tkinter`, `lzma`) from their packaged Python.
- Air-gapped boxes where you have populated the standalone cache and want pipx to ignore the system Python.
### Migrating from `--fetch-missing-python`
`--fetch-missing-python` and `PIPX_FETCH_MISSING_PYTHON` still work, but pipx warns and treats them as deprecated. They
behave like `--fetch-python=missing` / `PIPX_FETCH_PYTHON=missing`. pipx errors out if you set both
`PIPX_FETCH_MISSING_PYTHON` and `PIPX_FETCH_PYTHON`.
pipx-1.14.0/docs/how-to/troubleshoot.md 0000664 0000000 0000000 00000022045 15210205776 0020005 0 ustar 00root root 0000000 0000000 ## Wrong package version installed
pipx creates venvs using your default Python interpreter. pip resolves the latest package version compatible with that
interpreter. If a package drops support for your Python version, pip installs an older release without warning.
Check which Python pipx uses with `pipx environment --value PIPX_DEFAULT_PYTHON`. To install with a different Python,
pass `--python`:
```
pipx install my-package --python python3.12
```
If you don't have the desired Python version installed, pass `--fetch-python=missing` and pipx downloads a standalone
build:
```
pipx install my-package --python 3.13 --fetch-python=missing
```
Pass `--fetch-python=always` to download a standalone build even when the system already has the requested Python.
Useful when a distro ships a patched interpreter you'd rather avoid.
## `reinstall-all` fixes most issues
The following command should fix many problems you may encounter as a pipx user:
```
pipx reinstall-all
```
This is a good fix for the following problems:
- System python was upgraded and the python used with a pipx-installed package is no longer available
- pipx upgrade causes issues with old pipx-installed packages
pipx has been upgraded a lot over the years. If you are a long-standing pipx user (thanks, by the way!) then you may
have old pipx-installed packages that have internal data that is different than what pipx currently expects. By
executing `pipx reinstall-all`, pipx will re-write its internal data and this should fix many issues you may encounter.
**Note:** If your pipx-installed package was installed using a pipx version before 0.15.0.0 and you want to specify
particular options, then you may want to uninstall and install it manually:
```
pipx uninstall
pipx install
```
## Diagnosing problems using `list`
```
pipx list
```
will not only list all of your pipx-installed packages, but can also diagnose some problems with them, as well as
suggest solutions.
## Specifying pipx options
The most reliable method to specify command-line options that require an argument is to use an `=`-sign. An example:
```
pipx install pycowsay --pip-args="--no-cache-dir"
```
Another example for ignoring ssl/tls errors:
```
pipx install termpair --pip-args '--trusted-host files.pythonhosted.org --trusted-host pypi.org --trusted-host pypi.python.org --trusted-host github.com'"
```
## Check for `PIP_*` environment variables
pipx uses `pip` to install and manage packages. If you see pipx exhibiting strange behavior on install or upgrade, check
that you don't have special environment variables that affect `pip`'s behavior in your environment.
To check for `pip` environment variables, execute the following depending on your system:
### Unix or macOS
```
env | grep '^PIP_'
```
### Windows PowerShell
```
ls env:PIP_*
```
### Windows `cmd`
```
set PIP_
```
Reference: [pip Environment Variables](https://pip.pypa.io/en/stable/user_guide/#environment-variables)
## Clear `runpip` cache warnings
`pipx runpip` runs the `pip` installed in a pipx-managed virtual environment. Warnings such as
`WARNING: Cache entry deserialization failed, entry ignored` come from that `pip` process and its own HTTP cache, not
from pipx's virtual environment cache.
To clear the cache used by a pipx-managed package, run:
```
pipx runpip cache purge
```
To inspect the cache directory first, add `--verbose` so pipx does not quiet `pip`'s output:
```
pipx runpip --verbose cache dir
```
Clearing `$PIPX_HOME/.cache` or the cache for a different Python interpreter will not clear cache entries used by
`pipx runpip `.
## `pipx` log files
pipx records a verbose log file for every `pipx` command invocation. The logs for the last 10 `pipx` commands can be
found in `$XDG_STATE_HOME/pipx/logs` or user's log path if the former is not writable by the user. Set `PIPX_MAX_LOGS`
to change how many log files are kept (default: `10`).
For most users this location is `~/.local/state/pipx/logs`, where `~` is your home directory.
## `sudo pipx` not found
If you installed pipx with `pip install --user`, the binary lives in your user directory (e.g. `~/.local/bin/pipx`).
Root's `PATH` does not include that directory, so `sudo pipx` fails with "command not found". Use the full path instead:
```
sudo ~/.local/bin/pipx ensurepath --global
```
To avoid this, install pipx through your distribution's package manager (`apt install pipx`, `dnf install pipx`) or
install it system-wide with `sudo pip install pipx` (without `--user`).
## Debian, Ubuntu issues
If you have issues using pipx on Debian, Ubuntu, or other Debian-based linux distributions, make sure you have the
following packages installed on your system. (Debian systems do not install these by default with their python
installations.)
```
sudo apt install python3-venv python3-pip
```
Reference:
[Python Packaging User Guide: Installing pip/setuptools/wheel with Linux Package Managers](https://packaging.python.org/guides/installing-using-linux-tools)
## macOS issues
If you want to use a pipx-installed package in a shebang (a common example is the AWS CLI), you will likely not be able
to, because the binary will be stored under `~/Library/Application Support/pipx/`. The space in the path is not
supported in a shebang. A simple solution is symlinking `~/Library/Application Support/pipx` to
`~/Library/ApplicationSupport/pipx`, and using that as the path in the shebang instead.
```
mkdir $HOME/Library/ApplicationSupport
ln -s $HOME/Library/Application\ Support/pipx $HOME/Library/ApplicationSupport/pipx
```
## Does it work to install your package with `pip`?
This is a tip for advanced users. An easy way to check if pipx is the problem or a package you're trying to install is
the problem, is to try installing it using `pip`. For example:
### Unix or macOS
```
python3 -m venv test_venv
test_venv/bin/python3 -m pip install
```
### Windows
```
python -m venv test_venv
test_venv/Scripts/python -m pip install
```
If installation into this "virtual environment" using pip fails, then it's likely that the problem is with the package
or your host system.
To clean up after this experiment:
```
rm -rf test_venv
```
## pipx files not in expected locations according to documentation
pipx versions after 1.2.0 adopt the XDG base directory specification for the location of `PIPX_HOME` and the data,
cache, and log directories. Version 1.2.0 and earlier use `~/.local/pipx` as the default `PIPX_HOME` and install the
data, cache, and log directories under it. To maintain compatibility with older versions, pipx will automatically use
this old `PIPX_HOME` path if it exists. For a map of old and new paths, see [Installation Options](configure-paths.md).
In pipx version 1.5.0, this was reverted for Windows and macOS. It defaults again to `~/.local/pipx` on macOS and to
`~\pipx` on Windows.
If you have a `pipx` version later than 1.2.0 and want to migrate from the old path to the new paths, you can move the
`~/.local/pipx` directory to the new location (after removing cache, log, and trash directories which will get recreated
automatically) and then reinstall all packages.
Please refer to [Moving your pipx installation](move-installation.md) on how to move it.
## Warning: Found a space in the pipx home path
In pipx version 1.5, we introduced the warning you're seeing, as multiple incompatibilities with spaces in the pipx home
path were discovered. You may see this for the following reasons:
1. From pipx version 1.3 to 1.5, we were by default using a path with a space on it on macOS. This unfortunately means
that all users who installed pipx in this time frame and were using the default behavior are seeing this warning
now.
1. You set your `PIPX_HOME` to a path with spaces in it explicitly or because your `$HOME` path contains a space.
### Why are spaces in the `PIPX_HOME` path bad
The main reason we can't support paths with spaces is that shebangs don't support spaces in the interpreter path. All
applications installed via `pipx` are installed via `pip`, which creates a script with a shebang at the top, defining
the interpreter of the `venv` to use.
`pip` does some magic to the shebang for scripts defined as a `script`, that resolves this issue. Unfortunately, many
libraries define their scripts as `console_scripts`, where `pip` does not perform this logic. Therefore, these scripts
cannot be run if installed with `pipx` in a path with spaces because the path to the `venv` (and therefore the
interpreter) will contain spaces.
If you want to use a script installed via pipx in a shebang itself (common for example for the AWS CLI), you run into a
similar problem, as the path to the installed script will contain a space.
### How to fix
You can generally fix this by using our default locations, as long as your `$HOME` path does not contain spaces. Please
refer to our [Moving your pipx installation](move-installation.md) docs on how to move the `pipx` installation.
If you're really sure you want to stick to your path with spaces, to suppress the warning set the
`PIPX_HOME_ALLOW_SPACE` environment variable to `true`.
pipx-1.14.0/docs/how-to/upgrade-pipx.md 0000664 0000000 0000000 00000002043 15210205776 0017655 0 ustar 00root root 0000000 0000000 ## Upgrade pipx
On macOS:
```
brew update && brew upgrade pipx
```
On Ubuntu Linux:
```
sudo apt upgrade pipx
```
On Fedora Linux:
```
sudo dnf update pipx
```
On Windows:
```
scoop update pipx
```
Otherwise, upgrade via pip:
```
python3 -m pip install --user -U pipx
```
### Note: Upgrading pipx from a pre-0.15.0.0 version to 0.15.0.0 or later
After upgrading to pipx 0.15.0.0 or above from a pre-0.15.0.0 version, you must re-install all packages to take
advantage of the new persistent pipx metadata files introduced in the 0.15.0.0 release. These metadata files store pip
specification values, injected packages, any custom pip arguments, and more in each main package's venv.
If you have no packages installed using the `--spec` option, and no venvs with injected packages, you can do this by
running `pipx reinstall-all`.
If you have any packages installed using the `--spec` option or venvs with injected packages, you should reinstall
packages manually using `pipx uninstall-all`, followed by `pipx install` and possibly `pipx inject`.
pipx-1.14.0/docs/how-to/use-uv-backend.md 0000664 0000000 0000000 00000006700 15210205776 0020065 0 ustar 00root root 0000000 0000000 # Use the uv Backend
pipx can use [uv](https://github.com/astral-sh/uv) to create virtual environments, install packages, and run ephemeral
apps in place of pip and venv. The backend turns on when uv is reachable; flip it per command (`--backend`) or globally
(`PIPX_DEFAULT_BACKEND`).
> This page covers pipx using uv to create venvs and install packages. The pipx CLI surface stays the same. For a
> side-by-side comparison with `uv tool` (Astral's standalone command), see
> [pipx vs uv tool](../explanation/comparisons.md#pipx-vs-uv-tool).
## Why use it
- uv creates venvs faster than `python -m venv`. The venv ships without pip.
- uv resolves and installs faster than pip on large dependency trees.
- `pipx run` execs `uv tool run`, picking up uv's cross-invocation cache.
## Enable it
Two ways to expose uv to pipx:
1. Install pipx with the `uv` extra. pipx prefers the bundled binary when present:
```shell
pipx install pipx[uv]
```
1. Install uv however you like (`brew install uv`, `cargo install uv`, etc.) and put it on `PATH`. pipx picks it up
automatically.
When uv is available, pipx defaults to it for new venvs. Existing venvs keep their original backend; the choice lives in
each venv's metadata.
## Choose a backend explicitly
```shell
pipx install black --backend pip # force pip + venv
pipx install ruff --backend uv # force uv (errors if uv is not available)
PIPX_DEFAULT_BACKEND=uv pipx install ruff # global override via environment
pipx environment --value PIPX_RESOLVED_BACKEND # see what pipx will use right now
```
`install`, `install-all`, `inject`, `upgrade`, `upgrade-all`, `reinstall`, `reinstall-all`, and `run` all accept
`--backend`. Run `pipx reinstall NAME --backend uv` to switch an already-installed venv.
## What changes under the uv backend
- pipx creates new venvs with `uv venv`. The venv contains no `pip` and no `pipx_shared.pth` file.
- `pipx runpip` runs `uv pip --python /bin/python`. uv rejects flags it doesn't understand instead of pipx
silently dropping them.
- `pipx run` execs `uv tool run`; the cache lives in uv's cache directory. Pass `--no-cache` to skip it.
- `pipx run script.py` execs `uv run --script script.py` for PEP 723 inline scripts.
## Limitations
- `pipx install pip --backend uv` errors out. A uv venv has no pip, so the result would be inconsistent. Use
`--backend pip` instead.
- `pipx run --backend uv` does not honor `[pipx.run]` entry points; `uv tool run` only sees standard console scripts.
Use `--backend pip` if your package declares them.
- Some `--pip-args` values have no `uv tool run` equivalent (for example `--editable`, `--no-build-isolation`). pipx
errors instead of silently dropping them. Use `--backend pip` for those flows.
- `pipx run --backend uv` against URL or named-pipe scripts falls back to a pipx-managed venv: `uv run --script` reads
PEP 723 metadata off disk, and there is no on-disk path for content fetched at runtime. pipx logs a warning when
this fallback fires.
## Cache layout
`pipx run` under the uv backend caches in `UV_CACHE_DIR` instead of `PIPX_VENV_CACHEDIR`. Switching the default backend
on a host that already used `pipx run` leaves the old pipx cache behind: `pipx environment` prints both paths so you can
inspect them and remove the unused one manually. The 14-day expiry sweep that pipx applies to its own venv cache does
not extend to uv's cache, which uv manages on its own schedule (`uv cache clean`).
pipx-1.14.0/docs/how-to/use-with-pre-commit.md 0000664 0000000 0000000 00000001220 15210205776 0021063 0 ustar 00root root 0000000 0000000 ## Using pipx with pre-commit
pipx has [pre-commit](https://pre-commit.com/) support. This lets you run applications:
- that can be run using `pipx run` but don't have native pre-commit support;
- using its prebuilt wheel from pypi.org instead of building it from source; and
- using pipx's `--spec` and `--index-url` flags.
Example configuration for use of the code linter [yapf](https://github.com/google/yapf/). This is to be added to your
`.pre-commit-config.yaml`.
```yaml
- repo: https://github.com/pypa/pipx
rev: 1.5.0
hooks:
- id: pipx
alias: yapf
name: yapf
args: [yapf, -i]
types: [python]
```
pipx-1.14.0/docs/index.md 0000664 0000000 0000000 00000010556 15210205776 0015152 0 ustar 00root root 0000000 0000000
# pipx โ Install and Run Python Applications in Isolated Environments
pipx installs and runs end-user Python applications in isolated environments. It fills the same role as macOS's `brew`,
JavaScript's [npx](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b), and Linux's `apt`.
Under the hood it uses pip, but unlike pip it creates a separate virtual environment for each application, keeping your
system clean.
## Documentation
- **[Tutorials](tutorial/index.md)** โ install your first application and run commands in temporary environments.
- **[How-to Guides](how-to/index.md)** โ recipes for installing pipx, injecting packages, configuring paths, and more.
- **[Reference](reference/index.md)** โ CLI flags, examples, environment variables, and programs to try.
- **[Explanation](explanation/index.md)** โ how pipx works under the hood and how it compares to other tools.
```mermaid
flowchart LR
USER["you"] --> |"pipx install"| PIPX["pipx"]
USER --> |"pipx run"| PIPX
PIPX --> |"fetches from"| PYPI["PyPI"]
PIPX --> |"creates"| VENV["isolated venvs"]
VENV --> |"exposes on PATH"| APPS["black, ruff, poetry, ..."]
style USER fill:#3f72af,color:#fff
style PIPX fill:#2a9d8f,color:#fff
style PYPI fill:#c78c20,color:#fff
style VENV fill:#7c4dff,color:#fff
style APPS fill:#388e3c,color:#fff
```
## pip vs pipx
pip installs both libraries and applications into your current environment with no isolation. pipx installs only
applications, each in its own virtual environment, and exposes their commands on your `PATH`. You get clean uninstalls
and zero dependency conflicts between tools.
## Where do apps come from?
pipx pulls packages from [PyPI](https://pypi.org/) by default, but accepts any source pip supports: local directories,
wheels, and git URLs. Any package that declares
[console script entry points](https://python-packaging.readthedocs.io/en/latest/command-line-scripts.html#the-console-scripts-entry-point)
works with pipx. [Poetry](https://python-poetry.org/docs/pyproject/#scripts) and
[hatch](https://hatch.pypa.io/latest/config/metadata/#cli) users can add entry points the same way.
## Features
pipx lets you
- install CLI apps into isolated environments with `pipx install`, guaranteeing no dependency conflicts and clean
uninstalls;
- list, upgrade, and uninstall packages in one command; and
- run the latest version of any app in a temporary environment with `pipx run`.
pipx runs with regular user permissions and never calls `sudo pip install`.
## Testimonials
> "Thanks for improving the workflow that pipsi has covered in the past. Nicely done!"
>
> โ *[Jannis Leidel](https://twitter.com/jezdez), 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](https://twitter.com/jacobian), co-creator of Django in blog post
> [My Python Development Environment, 2020 Edition](https://jacobian.org/2019/nov/11/python-environment-2020/)*
> "I'm a big fan of pipx. I think pipx is super cool."
>
> โ *[Michael Kennedy](https://twitter.com/mkennedy), co-host of PythonBytes podcast in
> [episode 139](https://pythonbytes.fm/episodes/transcript/139/f-yes-for-the-f-strings)*
## 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)
pipx-1.14.0/docs/reference/ 0000775 0000000 0000000 00000000000 15210205776 0015450 5 ustar 00root root 0000000 0000000 pipx-1.14.0/docs/reference/environment-variables.md 0000664 0000000 0000000 00000007642 15210205776 0022315 0 ustar 00root root 0000000 0000000 ## Environment Variables
pipx reads the following environment variables. All are optional.
| Variable | Description | Default |
| --------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `PIPX_HOME` | Root directory for pipx virtual environments. | `~/.local/share/pipx` (Linux), `~/.local/pipx` (macOS), `~\pipx` (Windows) |
| `PIPX_BIN_DIR` | Directory where application entry-point symlinks are placed. | `~/.local/bin` |
| `PIPX_MAN_DIR` | Directory where man page symlinks are placed. | `~/.local/share/man` |
| `PIPX_GLOBAL_HOME` | Root directory for global (`--global`) virtual environments. | `/opt/pipx` |
| `PIPX_GLOBAL_BIN_DIR` | Binary directory for global installs. | `/usr/local/bin` |
| `PIPX_GLOBAL_MAN_DIR` | Man page directory for global installs. | `/usr/local/share/man` |
| `PIPX_DEFAULT_PYTHON` | Python interpreter to use when `--python` is not passed. | `python3` (or `py` on Windows) |
| `PIPX_DEFAULT_BACKEND` | Backend for new venvs: `pip` or `uv`. | `uv` when uv is available, else `pip` |
| `PIPX_SHARED_LIBS` | Override the shared libraries directory. | `PIPX_HOME/shared` |
| `PIPX_FETCH_PYTHON` | When to fetch a standalone Python build: `always`, `missing`, or `never`. | `never` |
| `PIPX_FETCH_MISSING_PYTHON` | Deprecated, alias for `PIPX_FETCH_PYTHON=missing`. | _(unset)_ |
| `PIPX_DISABLE_SHARED_LIBS_AUTO_UPGRADE` | Set to `1` to skip automatic shared library upgrades. | _(unset)_ |
| `PIPX_HOME_ALLOW_SPACE` | Set to `true` to suppress the "space in PIPX_HOME" warning. | _(unset)_ |
| `PIPX_USE_EMOJI` | Set to `0` to disable emoji output. | `1` |
| `PIPX_MAX_LOGS` | Maximum number of log files to keep in the logs directory. | `10` |
### Notes
`PIPX_HOME` has platform-specific fallback logic. If a legacy directory (e.g. `~/.local/pipx` on Linux) already exists,
pipx uses it instead of the new default. See [Configure Paths](../how-to/configure-paths.md) for details.
Standard `PIP_*` environment variables (e.g. `PIP_INDEX_URL`) are forwarded to pip when pipx invokes it. See
[Troubleshooting](../how-to/troubleshoot.md#check-for-pip_-environment-variables) if unexpected pip behaviour occurs.
Run `pipx environment` to see the resolved value of every directory variable on your system.
pipx-1.14.0/docs/reference/examples.md 0000664 0000000 0000000 00000016535 15210205776 0017622 0 ustar 00root root 0000000 0000000 ## `pipx install` examples
```
pipx install pycowsay
pipx install --python python3.10 pycowsay
pipx install --python 3.12 pycowsay
pipx install --fetch-python=missing --python 3.12 pycowsay
pipx install --fetch-python=always --python 3.13 pycowsay
pipx install git+https://github.com/psf/black
pipx install git+https://github.com/psf/black.git@branch-name
pipx install git+https://github.com/psf/black.git@git-hash
pipx install git+ssh://@/
pipx install https://github.com/psf/black/archive/18.9b0.zip
pipx install black[d]
pipx install --preinstall ansible-lint --preinstall mitogen ansible-core
pipx install 'black[d] @ git+https://github.com/psf/black.git@branch-name'
pipx install --suffix @branch-name 'black[d] @ git+https://github.com/psf/black.git@branch-name'
pipx install --include-deps jupyter
pipx install --pip-args='--pre' poetry
pipx install --pip-args='--index-url=: --trusted-host=:' private-repo-package
pipx install --index-url https://test.pypi.org/simple/ --pip-args='--extra-index-url https://pypi.org/simple/' some-package
pipx install --global pycowsay
pipx install .
pipx install path/to/some-project
```
## `pipx run` examples
pipx enables you to test various combinations of Python versions and package versions in ephemeral environments:
```
pipx run BINARY # latest version of binary is run with python3
pipx run --spec PACKAGE==2.0.0 BINARY # specific version of package is run
pipx run --python python3.10 BINARY # Installed and invoked with specific Python version
pipx run --python python3.10 --spec PACKAGE=1.7.3 BINARY
pipx run --spec git+https://url.git BINARY # latest version on default branch is run
pipx run --spec git+https://url.git@branch BINARY
pipx run --spec git+https://url.git@hash BINARY
pipx run pycowsay moo
pipx --version # prints pipx version
pipx run pycowsay --version # prints pycowsay version
pipx run --python pythonX pycowsay
pipx run pycowsay==2.0 --version
pipx run pycowsay[dev] --version
pipx run --spec git+https://github.com/psf/black.git black
pipx run --spec git+https://github.com/psf/black.git@branch-name black
pipx run --spec git+https://github.com/psf/black.git@git-hash black
pipx run --spec https://github.com/psf/black/archive/18.9b0.zip black --help
pipx run https://gist.githubusercontent.com/cs01/fa721a17a326e551ede048c5088f9e0f/raw/6bdfbb6e9c1132b1c38fdd2f195d4a24c540c324/pipx-demo.py
```
You can run local files, or scripts hosted on the internet, and you can run them with arguments:
```
pipx run test.py
pipx run test.py 1 2 3
pipx run https://example.com/test.py
pipx run https://example.com/test.py 1 2 3
```
A simple filename is ambiguous - it could be a file, or a package on PyPI. It will be treated as a filename if the file
exists, or as a package if not. To force interpretation as a local path, use `--path`, and to force interpretation as a
package name, use `--spec` (with the PyPI name of the package).
```
pipx run myscript.py # Local file, if myscript.py exists
pipx run doesnotexist.py # Package, because doesnotexist.py is not a local file
pipx run --path test.py # Always a local file
pipx run --spec test-py test.py # Always a package on PyPI
```
You can also run scripts that have dependencies:
If you have a script `test.py` that needs 3rd party libraries, you can add
[inline script metadata](https://packaging.python.org/en/latest/specifications/inline-script-metadata/) in the style of
PEP 723.
```
# test.py
# /// script
# dependencies = ["requests"]
# ///
import sys
import requests
project = sys.argv[1]
pipx_data = requests.get(f"https://pypi.org/pypi/{project}/json").json()
print(pipx_data["info"]["version"])
```
Then you can run it as follows:
```
> pipx run test.py pipx
1.1.0
```
## `pipx inject` example
One use of the inject command is setting up a REPL with some useful extra packages.
```
> pipx install ptpython
> pipx inject ptpython requests pendulum
```
After running the above commands, you will be able to import and use the `requests` and `pendulum` packages inside a
`ptpython` repl.
Equivalently, the extra packages can be listed in a text file (e.g. `useful-packages.txt`). Each line is a separate
package specifier with the same syntax as the command line. Comments are supported with a `#` prefix. Hence, the syntax
is a strict subset of the pip [requirements file format][pip-requirements] syntax.
```
# Additional packages
requests
pendulum # for easier datetimes
```
This file can then be given to `pipx inject` on the command line:
```shell
> pipx inject ptpython --requirement useful-packages.txt
# or:
> pipx inject ptpython -r useful-packages.txt
```
Note that these options can be repeated and used together, e.g.
```
> pipx inject ptpython package-1 -r extra-packages-1.txt -r extra-packages-2.txt package-2
```
If you require full pip functionality, then use the `runpip` command instead; however, the installed packages won't be
recognised as "injected".
## `pipx list` example
```
> pipx list
venvs are in /Users/user/.local/pipx/venvs
binaries are exposed on your $PATH at /Users/user/.local/bin
package black 18.9b0, Python 3.10.0
- black
- blackd
package pipx 0.10.0, Python 3.10.0
- pipx
> pipx list --short
black 18.9b0
pipx 0.10.0
```
## `pipx install-all` example
```shell
> pipx list --json > pipx.json
> pipx install-all pipx.json
'black' already seems to be installed. Not modifying existing installation in '/usr/local/pipx/venvs/black'. Pass '--force' to force installation.
'pipx' already seems to be installed. Not modifying existing installation in '/usr/local/pipx/venvs/black'. Pass '--force' to force installation.
> pipx install-all pipx.json --force
Installing to existing venv 'black'
installed package black 24.3.0, installed using Python 3.10.12
These apps are now globally available
- black
- blackd
done! โจ ๐ โจ
Installing to existing venv 'pipx'
installed package pipx 1.4.3, installed using Python 3.10.12
These apps are now globally available
- pipx
done! โจ ๐ โจ
```
## `pipx upgrade-shared` examples
One use of the upgrade-shared command is to force a `pip` upgrade.
```shell
> pipx upgrade-shared
```
This example pins `pip` (temporarily, until the next automatic upgrade, if that is not explicitly turned off) to a
specific version.
```shell
> pipx upgrade-shared --pip-args=pip==24.0
```
## `pipx pin` examples
Pinning keeps an installation at its current version until you call `pipx unpin`.
Pin the entire environment (main package plus anything injected):
```shell
> pipx install httpie
> pipx pin httpie
> pipx list --pinned
httpie
```
Pin only injected packages so the main package can continue to receive upgrades:
```shell
> pipx inject poetry poetry-plugin-export poetry-plugin-app
> pipx pin poetry --injected-only
Pinned 2 packages in venv poetry
- poetry-plugin-export
- poetry-plugin-app
```
Skip selected injected packages when pinning:
```shell
> pipx inject pdm pdm-django pdm-pytorch
> pipx pin pdm --skip pdm-django
Pinned 1 packages in venv pdm
- pdm-pytorch
```
Unpin everything so upgrades resume:
```shell
> pipx unpin poetry
Unpinned 2 packages in venv poetry
- poetry
- poetry-plugin-export
- poetry-plugin-app
```
[pip-requirements]: https://pip.pypa.io/en/stable/reference/requirements-file-format/
pipx-1.14.0/docs/reference/index.md 0000664 0000000 0000000 00000000732 15210205776 0017103 0 ustar 00root root 0000000 0000000 # Reference
Technical reference for pipx: CLI flags, environment variables, and runnable examples.
- [CLI Reference](cli.md) โ auto-generated help text for every pipx command.
- [Examples](examples.md) โ copy-paste command examples for install, run, inject, list, and more.
- [Programs to Try](programs-to-try.md) โ Python applications worth installing with pipx.
- [Environment Variables](environment-variables.md) โ every `PIPX_*` variable and what it controls.
pipx-1.14.0/docs/reference/programs-to-try.md 0000664 0000000 0000000 00000003765 15210205776 0021073 0 ustar 00root root 0000000 0000000 ## Programs
Here are some programs you can try out. If you've never used the program before, make sure you add the `--help` flag so
it doesn't do something you don't expect. If you decide you want to install, you can run `pipx install PACKAGE` instead.
### ansible
IT automation
```
pipx install --include-deps ansible
```
### asciinema
Record and share your terminal sessions, the right way.
```
pipx run asciinema
```
### black
uncompromising Python code formatter
```
pipx run black
```
### pybabel
internationalizing and localizing Python applications
```
pipx run --spec=babel pybabel --help
```
### chardetect
detect file encoding
```
pipx run --spec=chardet chardetect --help
```
### cookiecutter
creates projects from project templates
```
pipx run cookiecutter
```
### create-python-package
easily create and publish new Python packages
```
pipx run create-python-package
```
### flake8
tool for style guide enforcement
```
pipx run flake8
```
### gdbgui
browser-based gdb debugger
```
pipx run gdbgui
```
### hatch
Python project manager that lets you build & publish packages, run tasks in environments and more
```
pipx run hatch
```
### hexsticker
create hexagon stickers automatically
```
pipx run hexsticker
```
### ipython
powerful interactive Python shell
```
pipx run ipython
```
### jupyter
web-based notebook environment for interactive computing
```
pipx run jupyter
```
### pipenv
python dependency/environment management
```
pipx run pipenv
```
### poetry
python dependency/environment/packaging management
```
pipx run poetry
```
### pylint
source code analyzer
```
pipx run pylint
```
### pyinstaller
bundles a Python application and all its dependencies into a single package
```
pipx run pyinstaller
```
### pyxtermjs
fully functional terminal in the browser
```
pipx run pyxtermjs
```
### ruff
An extremely fast Python linter
```
pipx run ruff
```
### shell-functools
Functional programming tools for the shell
```
pipx install shell-functools
```
pipx-1.14.0/docs/tutorial/ 0000775 0000000 0000000 00000000000 15210205776 0015355 5 ustar 00root root 0000000 0000000 pipx-1.14.0/docs/tutorial/getting-started.md 0000664 0000000 0000000 00000002704 15210205776 0021007 0 ustar 00root root 0000000 0000000 ## Getting Started with pipx
This tutorial covers the core pipx workflow: installing an application, running it, and managing it. You need
[pipx installed](../how-to/install-pipx.md) before continuing.
### Install your first application
Pick a small package to try. `pycowsay` works well:
```
pipx install pycowsay
```
pipx creates an isolated virtual environment for `pycowsay`, installs it there, and links the `pycowsay` command into a
directory on your `PATH`. Run it from anywhere:
```
pycowsay "Hello, pipx!"
```
### List installed applications
```
pipx list
```
The output shows the virtual environment location, exposed commands, and the Python version each package uses.
### Run an application without installing
`pipx run` executes an application in a temporary environment and cleans up after itself:
```
pipx run pycowsay moooo!
```
### Upgrade an installed application
```
pipx upgrade pycowsay
```
Or upgrade everything at once:
```
pipx upgrade-all
```
### Uninstall an application
```
pipx uninstall pycowsay
```
pipx deletes the isolated environment and removes the command from your `PATH`.
### Next steps
Continue with the [install applications](install-applications.md) and [run applications](run-applications.md) tutorials
for a closer look at the two core commands. The [how-to guides](../how-to/index.md) cover tasks like injecting packages
and configuring paths. The full [CLI reference](../reference/cli.md) documents every flag.
pipx-1.14.0/docs/tutorial/index.md 0000664 0000000 0000000 00000000642 15210205776 0017010 0 ustar 00root root 0000000 0000000 # Tutorials
Step-by-step lessons that take you from zero to productive with pipx. Start from the top if you are new.
- [Getting Started](getting-started.md) โ install your first application and learn the core commands.
- [Install Applications](install-applications.md) โ `pipx install` with real examples.
- [Run Applications](run-applications.md) โ `pipx run` for one-off execution in temporary environments.
pipx-1.14.0/docs/tutorial/install-applications.md 0000664 0000000 0000000 00000003173 15210205776 0022035 0 ustar 00root root 0000000 0000000 ## Installing a Package and its Applications
Install an application with:
```
pipx install PACKAGE
```
pipx creates a virtual environment, installs the package, and adds its entry points to a location on your `PATH`.
`pipx install pycowsay` makes the `pycowsay` command available system-wide while sandboxing pycowsay in its own virtual
environment. No `sudo` required. To install for all users on the system, pass `--global` after the subcommand (see
[Configure Paths](../how-to/configure-paths.md#-global-argument)).
```
>> 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 |
|| ||
```
### Picking a Python interpreter
Pass `--python` to install with a specific Python version. When that Python isn't on your `PATH`, pipx can download a
[python-build-standalone](https://github.com/astral-sh/python-build-standalone) build for you:
```
pipx install --python 3.13 --fetch-python=missing pycowsay
```
Pass `--fetch-python=always` to use a fresh standalone build instead of any system Python. Reach for it when a distro
patched the system Python in ways you can't tolerate. See the [Standalone Python](../how-to/standalone-python.md) how-to
for more options.
pipx-1.14.0/docs/tutorial/run-applications.md 0000664 0000000 0000000 00000006166 15210205776 0021200 0 ustar 00root root 0000000 0000000 ## Running an Application in a Temporary Virtual Environment
`pipx run` downloads and runs Python applications in a one-time, temporary environment, then leaves your system
untouched. Use it to initialize a new project, check an app's help text, or try a tool without committing to an install.
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).
```
pipx run APP [ARGS...]
```
pipx installs the package in an isolated, temporary directory and invokes the app:
```
> pipx run pycowsay moo
---
< moo >
---
\ ^__^
\ (oo)\_______
(__)\ )\/\
||----w |
|| ||
```
Arguments after the application name pass straight through:
```
> pipx run pycowsay these arguments are all passed to pycowsay!
-------------------------------------------
< these arguments are all passed to pycowsay! >
-------------------------------------------
\ ^__^
\ (oo)\_______
(__)\ )\/\
||----w |
|| ||
```
pipx caches virtual environments per app for a few days. After they expire, pipx fetches the latest version.
### Ambiguous arguments
pipx can consume arguments meant 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
```
Place `--` before the app name to forward all arguments verbatim:
```
> pipx run -- pycowsay --py
----
< --py >
----
\ ^__^
\ (oo)\_______
(__)\ )\/\
||----w |
|| ||
```
### App name differs from package name
Use `--spec` to specify the package and provide the app name separately:
```
pipx run --spec PACKAGE APP
```
The [esptool](https://github.com/espressif/esptool) package, for example, exposes executables with different names:
```
>> 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?]'
```
Run them with `--spec`:
```
pipx run --spec esptool esptool.py
```
The `.py` is part of the executable name as declared by the package. The
[pymodbus](https://github.com/pymodbus-dev/pymodbus) package shows a similar pattern:
```
pipx run --spec pymodbus[repl] pymodbus.console
pipx run --spec pymodbus[repl] pymodbus.server
pipx run --spec pymodbus[repl] pymodbus.simulator
```
Package authors can avoid this `--spec` requirement by declaring a
[`pipx.run` entry point](../explanation/making-packages-compatible.md#the-pipxrun-entry-point-group) in their package
metadata.
pipx-1.14.0/get-pipx.py 0000775 0000000 0000000 00000000526 15210205776 0014677 0 ustar 00root root 0000000 0000000 #!/usr/bin/env python3
import sys
def fail(msg):
sys.stderr.write(msg + "\n")
sys.stderr.flush()
sys.exit(1)
def main():
fail(
"This installation method has been obsoleted. "
"See https://github.com/pypa/pipx for current installation "
"instructions."
)
if __name__ == "__main__":
main()
pipx-1.14.0/logo.svg 0000664 0000000 0000000 00000200370 15210205776 0014245 0 ustar 00root root 0000000 0000000
pipx-1.14.0/mkdocs.yml 0000664 0000000 0000000 00000005061 15210205776 0014567 0 ustar 00root root 0000000 0000000 site_name: pipx
site_description: execute binaries from Python packages in isolated environments
theme:
name: "material"
palette:
- media: "(prefers-color-scheme: light)"
scheme: default
toggle:
icon: material/brightness-7
name: Switch to dark mode
- media: "(prefers-color-scheme: dark)"
scheme: slate
toggle:
icon: material/brightness-4
name: Switch to light mode
features:
- navigation.tabs
- navigation.tabs.sticky
- navigation.indexes
- toc.integrate
- content.tabs.link
- content.code.copy
repo_name: pypa/pipx
repo_url: https://github.com/pypa/pipx
edit_uri: edit/main/docs/
extra:
analytics:
provider: 'google'
property: 'UA-90243909-2'
nav:
- Home: "index.md"
- Tutorials:
- tutorial/index.md
- Getting Started: "tutorial/getting-started.md"
- Install Applications: "tutorial/install-applications.md"
- Run Applications: "tutorial/run-applications.md"
- How-to Guides:
- how-to/index.md
- Install pipx: "how-to/install-pipx.md"
- Upgrade pipx: "how-to/upgrade-pipx.md"
- Inject Packages: "how-to/inject-packages.md"
- Pin Packages: "how-to/pin-packages.md"
- Run Scripts: "how-to/run-scripts.md"
- Use the uv Backend: "how-to/use-uv-backend.md"
- Use with pre-commit: "how-to/use-with-pre-commit.md"
- Configure Paths: "how-to/configure-paths.md"
- Move Installation: "how-to/move-installation.md"
- Shell Completions: "how-to/shell-completions.md"
- Troubleshoot: "how-to/troubleshoot.md"
- Reference:
- reference/index.md
- CLI Reference: "reference/cli.md"
- Examples: "reference/examples.md"
- Programs to Try: "reference/programs-to-try.md"
- Environment Variables: "reference/environment-variables.md"
- Explanation:
- explanation/index.md
- How pipx Works: "explanation/how-pipx-works.md"
- Comparisons: "explanation/comparisons.md"
- Making Packages Compatible: "explanation/making-packages-compatible.md"
- Contributing: "contributing.md"
- Changelog: "changelog.md"
markdown_extensions:
- markdown_gfm_admonition # GitHub's admonition (alert) syntax
- footnotes
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
- pymdownx.tabbed:
alternate_style: true
plugins:
- search:
lang: en
- gen-files:
scripts:
- scripts/gen_doc_pages.py
- macros
exclude_docs: |
README.md
pipx-1.14.0/pipx_demo.gif 0000664 0000000 0000000 00001007517 15210205776 0015250 0 ustar 00root root 0000000 0000000 GIF89a$๗ 1 H
IN
EEP=#E
6(771*T
$"0_#
$8$ ('.'%/)#)
)* +(+#,,&,B,:g- --1.1#H33>3O44 4,U5)8
8C`9 9:E;,_;Ar<3D=Pu>>5h>;R??F}A;B C&QFG.GVdH0EH1;JJ+#K(NWsOOH~ORP3P0ZQT*"T.7T4JT7VTBnV+WBYY*[f]1^Y_52`Gs`V_actd7CdQvep hDUi3&mSEn:nJ`nขpW`s:1sRtouK.uL2uM6w~ตxzJUzTf{^u{`V|SA}SX} ~bgq}qนACpODQ| ^eesj]ขร\Ui@ฒจss]~คถxti @กฝฆูqจฤฃtฃฏไฆฒ็งณๆจi^ซญ นฎwgฎdฏฆอฐฝ๏ณณฟูดtดดนรตถsถถทฅฅธญฯธฐซน@นดญผnพนดพฮ๘ฟำรoฦ`<ฦฯศพลศู๙ฬอศํฮทฅฯยูะชะ฿๛ัฐรัผซาีืำฅิิฌฑิฑงิฟีฝซึฅfึบทึใุิ๓ฺศถยลืํ๙ํน8แฒแิยไธฆๆฌๆป8ๆฺ๐ๆโ๗ๆ๐ๆ๛็ฏก็า็ๅไ้ฌ.๊ฮะ๋ฦ ๋สTฺ๋๋๓ุ์์ฤฤํฮiํฦ๎ฟฌ๕ยณ๖ห9๖์๗ฺ,๘ไ ๙ห/๙๘๚ฺ9๚็๑๛ัท๛0๛๘ายุั๏๒ลแศ๖๎เ฿ๅฺๆฮ๎ำ๏๐๚!NETSCAPE2.0 !๙
, $ -Hฐ ม*\ศฐกร#JHฑขล3jศฑฃว CIฒคษ(Sช\ษฒฅห0cสIณฆอ8s๊ษณงฯ@
JดจัฃH*]สดฉำงPฃJJตชีซXณjสตซืฏ`รKถฌูณhำฅกถญทpใสE9ศถs๓๊หทฏ[u ๘LธฐแรIiุEฬธฑใวGบ oไห3kL7MบดZ8Lซ^อบต๋ืฐcหMปถํธs๋อปท๏฿ภNผธ๑ใศ+_ฮผน๓็ะฃKNฝบ๕ุ๋ณk฿ฮฝป๗๏เรOพผ๙๓่ำซ_ฯพฝ๛๗๐ใหOฟพ๛๘๓๋฿ฯฟฟ (เhเ&จเ6่เF(แVhแ fจแv่แ (โ$hโ(ฆจโ,ถ่โ0ฦ(ใ4ึhใ8ๆจใ<๖่ใ@)ไDiไH&ฉไL6้ไPF)ๅTViๅXfฉๅ\v้ๅ`)ๆdiๆhฆฉๆlถ้ๆpฦ)็tึi็xๆฉ็|๖้็*่ j่ก&ช่ข6๊่ฃF*้คVj้ฅfช้ฆv๊้ง *๊จคj๊ฉจฆช๊ชฌถ๊๊ซฐฦ*๋ฌดึj๋ญธๆช๋ฎผ๖๊๋ฏภ+์ฐฤk์ฑศ&ซ์ฒฬ6๋์ณะF+ํดิVkํตุfซํถv๋ํทเ+๎ธไk๎น่ฆซ๎บ์ถ๋๎ป๐ฦ+๏ผ๔ึk๏ฝ๘ๆซ๏พ๖๋๏ฟ ,๐ภl๐ม'ฌ๐ย7์๐รG,๑ฤWl๑ลgฌ๑ฦw์๑ว ,๒ศ$l๒ษ(งฌ๒ส,ท์๒ห0ว,๓ฬ4ืl๓อ8็ฌ๓ฮ<๗์๓ฯ@็์ ษ่Zะ๑J2จtX ย!พไRด;<` hK.พ$ึ"ร(ฐDcL-d/@ ภ"LMำq7@D"v฿๎6แ: ท*N# แบ8๎`เั0~ชถชโ7N*ๆDhฎชแc_9ซำ wฉB.zชW๎๙็ญฟ*ไจfn๛ฉฑ[njํปJบณy๑ผ๋๙ๅฎฃ.8+ศช;๊็^{ซQ`=ๆ7่z๐:๘แ8}๙ ~๚งฏเ๘๎ฟ฿~ชOื฿o๚h ๔ฟ๖็|<`๓xภ1p?|`~
(ม๛ฏ๚ก ้ม
rpฌB(B0><ก{.จB๙คฐ ๋้ ู๓ยขg6lsxC๒P=,!}(ฤ๓์ฐใฉ!มร%็Nฃศ RQ