Skip to content

# 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 for details.

Standard `PIP_*` environment variables (e.g. `PIP_INDEX_URL`) are forwarded to pip when pipx invokes it. See Troubleshooting if unexpected pip behaviour occurs.

Run `pipx environment` to see the resolved value of every directory variable on your system.