################
 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:

.. mermaid::

    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;

.. list-table::
    :header-rows: 1
    :widths: 30 45 25

    - - Variable
      - Holds
      - Default
    - - ``PIPX_HOME``
      - Virtual environments and shared libraries
      - ``~/.local/share/pipx``
    - - ``PIPX_BIN_DIR``
      - App links
      - ``~/.local/bin``
    - - ``PIPX_MAN_DIR``
      - Manual page links
      - ``~/.local/share/man``
    - - ``PIPX_COMPLETION_DIR``
      - Shell completion links
      - ``~/.local/share``

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:

***********************
 platformdirs migration
***********************

After version 1.16.0, pipx moved its default paths from ``~/.local/pipx`` to per-platform user directories from the
`platformdirs <https://pypi.org/project/platformdirs/>`_ library:

.. list-table::
    :header-rows: 1
    :widths: 40 60

    - - 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")``

For compatibility, if ``~/.local/pipx`` exists (on Windows also ``~\pipx``), pipx keeps using it. See the `platformdirs
platform table <https://platformdirs.readthedocs.io/en/latest/api.html#platforms>`_ 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 :doc:`move-installation`.

**********************
 Install for all users
**********************

Use ``--global`` **after** the subcommand to operate on the system-wide installation:

.. code-block:: console

    $ 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
:doc:`../reference/environment-variables`.

You can also set the variables yourself instead of using ``--global``:

.. code-block:: console

    $ 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:

.. code-block:: console

    $ 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 :doc:`use-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:

.. code-block:: console

    $ pipx install --skip-maintenance my-package

**********
 Verify it
**********

.. code-block:: console

    $ pipx environment --value PIPX_HOME
    $ pipx environment --value PIPX_BIN_DIR

Each prints the path pipx will use, reflecting any override you set.
