Configure paths¶
Choose where pipx stores environments, apps, manual pages, and shell completions, and how it installs for all users.
Directory layout¶
pipx splits its files across four locations, each with an environment-variable override and a --global counterpart:
flowchart TD
subgraph local["default (per-user)"]
H1["PIPX_HOME<br/>~/.local/share/pipx<br/>(venvs, shared libs)"]
B1["PIPX_BIN_DIR<br/>~/.local/bin<br/>(app links)"]
M1["PIPX_MAN_DIR<br/>~/.local/share/man<br/>(man page links)"]
C1["PIPX_COMPLETION_DIR<br/>~/.local/share<br/>(completion links)"]
end
subgraph glob["--global (all users)"]
H2["PIPX_GLOBAL_HOME<br/>/opt/pipx"]
B2["PIPX_GLOBAL_BIN_DIR<br/>/usr/local/bin"]
M2["PIPX_GLOBAL_MAN_DIR<br/>/usr/local/share/man"]
C2["PIPX_GLOBAL_COMPLETION_DIR<br/>/usr/local/share"]
end
classDef home fill:#2a9d8f,stroke:#1f7268,color:#fff;
classDef bin fill:#3f72af,stroke:#28507d,color:#fff;
classDef man fill:#7c4dff,stroke:#5a34c0,color:#fff;
classDef completion fill:#e76f51,stroke:#b4513a,color:#fff;
class H1,H2 home;
class B1,B2 bin;
class M1,M2 man;
class C1,C2 completion;
Variable |
Holds |
Default |
|---|---|---|
|
Virtual environments and shared libraries |
|
|
App links |
|
|
Manual page links |
|
|
Shell completion links |
|
The default PIPX_HOME is typically ~/.local/share/pipx on Linux, ~/Library/Application Support/pipx on
macOS, and %USERPROFILE%\AppData\Local\pipx\pipx on Windows. Set any variable to override its location.
platformdirs migration¶
After version 1.16.0, pipx moved its default paths from ~/.local/pipx to per-platform user directories from the
platformdirs library:
Old path |
New path |
|---|---|
|
|
|
|
|
|
|
|
|
|
For compatibility, if ~/.local/pipx exists (on Windows also ~\pipx), pipx keeps using it. See the platformdirs
platform table for the resolved directories. On
Linux and macOS, platformdirs reads XDG_DATA_HOME and XDG_CACHE_HOME, and on Linux also XDG_STATE_HOME
for the log directory, so exporting any of them moves the matching pipx directory; leave them unset for the platform
default.
pipx introduced these paths in 1.2.0 and reverted them for macOS and Windows between 1.5.0 and 1.16.0. To move an existing installation to the new default, see Move installation.
Install for all users¶
Use --global after the subcommand to operate on the system-wide installation:
$ sudo pipx install --global pycowsay
$ pipx list --global
Commands that write to the global locations need root. pipx environment --global only reads them, so any user can
run it. pipx list --global reads each environment’s pipx_metadata.json, which pipx keeps readable by its owner
only because it can hold index credentials. Other users see each environment reported as unreadable; run it with
sudo to list them.
Putting --global before the subcommand, as in sudo pipx --global install pycowsay, raises
unrecognized arguments: --global. For manifest, interpreter and cache it goes after their own
subcommand, as in sudo pipx manifest sync --global ./pipx.toml.
Default global paths are /usr/local/bin for binaries, /usr/local/share/man for man pages, /usr/local/share
for shell completions, and /opt/pipx for environments. Override them with PIPX_GLOBAL_BIN_DIR,
PIPX_GLOBAL_MAN_DIR, PIPX_GLOBAL_COMPLETION_DIR, and PIPX_GLOBAL_HOME.
Add the global binary directory to the system PATH with sudo pipx ensurepath --global, which writes
/etc/profile.d/pipx.sh on Linux and /etc/paths.d/pipx on macOS. pipx refuses to replace a file there that holds
anything besides the entry an earlier ensurepath --global wrote; add the directory yourself, or pass --force to
replace the file.
When you install pipx itself with --global and override PIPX_GLOBAL_HOME, set the override for every user (for
example in /etc/environment), so that pipx recognizes its own environment as the global one; see
Environment variables.
You can also set the variables yourself instead of using --global:
$ sudo PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin PIPX_MAN_DIR=/usr/local/share/man pipx install <PACKAGE>
Note
pipx does not support --global on Windows.
Prepend or preview the PATH edit¶
Pass --prepend to pipx ensurepath to prepend the pipx bin directory to PATH instead of appending it, so
pipx-installed binaries win over system binaries of the same name.
Pass --dry-run to report which directories ensurepath would add, without touching PATH or any shell
configuration file:
$ pipx ensurepath --dry-run
Point pip at an index¶
Under the pip backend, pipx uses pip for all installs, including its own shared libraries. Set PIP_* environment
variables to route pip at a private index; pipx forwards them to every pip call. The uv backend ignores PIP_*; use
uv’s own variables such as UV_INDEX_URL. For per-command control use --pip-args. See Use a private index
for the full recipe.
Set PIPX_DISABLE_SHARED_LIBS_AUTO_UPGRADE=1 to skip automatic shared-library upgrades during commands such as
pipx install and pipx upgrade; pipx upgrade-shared still upgrades them. Use --skip-maintenance to apply
the same policy to one command:
$ pipx install --skip-maintenance my-package
Verify it¶
$ pipx environment --value PIPX_HOME
$ pipx environment --value PIPX_BIN_DIR
Each prints the path pipx will use, reflecting any override you set.