#############
 Install pipx
#############

Get pipx onto your system and add its app directory to your ``PATH``.

pipx runs on macOS, Linux, and Windows.

***********************
 Check the requirements
***********************

Installing pipx needs Python 3.11 or newer, and so does any interpreter you pass with ``--python``. Without Python
3.11, see the `Python 3 installation guide <https://realpython.com/installing-python/>`_.

You also need ``pip`` for ``python3``. The steps vary by system; see `pip's installation instructions
<https://pip.pypa.io/en/stable/installation/>`_. On Linux, install through a `Linux package manager
<https://packaging.python.org/guides/installing-using-linux-tools/#installing-pip-setuptools-wheel-with-linux-package-managers>`_.

***************
 Install per OS
***************

macOS
=====

.. code-block:: console

    $ brew install pipx
    $ pipx ensurepath

Linux
=====

Ubuntu 23.04 or newer:

.. code-block:: console

    $ sudo apt update
    $ sudo apt install pipx
    $ pipx ensurepath

Fedora:

.. code-block:: console

    $ sudo dnf install pipx
    $ pipx ensurepath

Other distributions, using ``pip``:

.. code-block:: console

    $ python3 -m pip install --user pipx
    $ python3 -m pipx ensurepath

.. warning::

    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, so ``pip install --user`` fails with ``externally-managed-environment``.
    Use the distribution package (``apt install pipx``, ``dnf install pipx``). If none exists, install pipx into its own
    virtual environment:

    .. code-block:: console

        $ 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

Windows
=======

Install via `Scoop <https://scoop.sh/>`_:

.. code-block:: console

    $ scoop install pipx
    $ pipx ensurepath

Install via pip (needs pip 19.0 or newer; replace ``py`` with ``python3`` if you installed Python from the Microsoft
Store):

.. code-block:: console

    $ py -m pip install --user pipx

This often ends with a warning that ``pipx.exe`` is installed in a directory that is not on ``PATH``. Go to that
directory and run the executable directly to fix it (run this even without the warning):

.. code-block:: console

    $ .\pipx.exe ensurepath

This adds both that directory and ``%USERPROFILE%\.local\bin`` to your search path. Restart the terminal, then confirm
``pipx`` runs.

FreeBSD
=======

.. code-block:: console

    $ pkg install -y py311-pipx
    $ pipx ensurepath

Or via pip:

.. code-block:: console

    $ pip install --user pipx
    $ pipx ensurepath

***********************
 Optional PATH commands
***********************

Add the global app directory to the system ``PATH`` (pipx 1.6.0+):

.. code-block:: console

    $ sudo pipx ensurepath --global

Prepend the pipx bin directory instead of appending it, so pipx apps win over system apps of the same name (pipx
1.7.0+):

.. code-block:: console

    $ pipx ensurepath --prepend

For where these directories live and how to change them, see :doc:`configure-paths`.

.. note::

    Some distributions ship older pipx versions (Ubuntu 24.04 ships 1.4.3). If ``--global`` or ``--prepend`` fails with
    "unrecognized arguments", :doc:`upgrade pipx <upgrade-pipx>` first.

.. tip::

    ``sudo pipx`` reports "command not found" when pipx lives in your user directory. See :ref:`sudo-pipx-not-found` for
    the fix.

****************************
 Run pipx without installing
****************************

Download the zipapp from `GitHub releases <https://github.com/pypa/pipx/releases>`_ and invoke it with a Python 3.11+
interpreter:

.. code-block:: console

    $ python pipx.pyz ensurepath

******************
 Self-managed pipx
******************

Let pipx manage its own installation so ``pipx upgrade pipx`` keeps it current and you avoid distro packages that ship
older versions. Bootstrap it through a throwaway virtual environment in a fresh private directory:

.. code-block:: console

    $ bootstrap=$(mktemp -d)
    $ python3 -m venv "$bootstrap"
    $ "$bootstrap/bin/pip" install pipx
    $ "$bootstrap/bin/pipx" install pipx
    $ "$bootstrap/bin/pipx" ensurepath
    $ rm -rf "$bootstrap"

``mktemp -d`` creates a directory with a random name that only you can enter. Avoid a fixed path such as
``/tmp/bootstrap``: on a shared host another user can create it first and plant code that every Python process started
from the bootstrap runs, including the ``sudo`` step below.

After this, ``pipx upgrade pipx`` upgrades pipx like any other managed app. 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.

To share one self-managed pipx between all users on Unix, run the bootstrap's ``install`` with ``sudo`` and
``--global`` instead, before removing the bootstrap directory. The installed ``pipx`` then works on each user's own
environments, and on the global ones only when you pass ``--global``:

.. code-block:: console

    $ sudo "$bootstrap/bin/pipx" install --global pipx
    $ pipx install pycowsay
    $ sudo pipx install --global pycowsay

.. _install-from-source-control:

****************************
 Install from source control
****************************

pipx accepts any source pip supports, including git repositories. Using ``black`` as an example:

.. code-block:: console

    $ pipx install git+https://github.com/psf/black.git
    $ pipx install git+ssh://git@github.com/psf/black
    $ pipx install git+https://github.com/psf/black.git@branch
    $ pipx install git+https://github.com/psf/black.git@258e7dbf348bc23cb70b8cdf693481c04634ebcc
    $ pipx install https://github.com/psf/black/archive/18.9b0.zip

Use a direct URL requirement to install extras:

.. code-block:: console

    $ pipx install "black[jupyter] @ git+https://github.com/psf/black.git"

To test a package from an open pull request, find the fork owner and branch on the PR page, then build the git URL. For
PR #794 from user ``contributor`` on branch ``fix-something``:

.. code-block:: console

    $ pipx install git+https://github.com/contributor/pipx.git@fix-something

If the branch is already merged, use the merge commit hash instead:

.. code-block:: console

    $ pipx install git+https://github.com/pypa/pipx.git@abc123def

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

.. code-block:: console

    $ pipx --version

Open a new terminal after ``pipx ensurepath`` so the updated ``PATH`` takes effect, then run ``pipx list`` to confirm
the environment is reachable.
