################
 Inject packages
################

Add extra packages into an existing pipx-managed environment with ``pipx inject``.

*****************
 Inject a package
*****************

Add ``matplotlib`` to the ``ipython`` environment:

.. code-block:: console

    $ pipx inject ipython matplotlib

Inject several at once, from a requirements file, or both:

.. code-block:: console

    $ pipx inject ipython matplotlib pandas
    $ pipx inject ipython -r useful-packages.txt
    $ pipx inject ipython extra-pkg -r more-packages.txt

Scripts can request the versioned result envelope from either command:

.. code-block:: console

    $ pipx inject ipython matplotlib --output json
    $ pipx uninject ipython matplotlib --output json

****************************************
 Add an extra to the environment's app
****************************************

Name the main package with the extra to add it. pipx installs the extra from the app's recorded source, so an app
installed from a wheel, a directory or a URL keeps that source and the extras it already had:

.. code-block:: console

    $ pipx install ./mytool-1.0-py3-none-any.whl
    $ pipx inject mytool 'mytool[feature]'

A spec that changes anything besides the extras, such as a version or a different path or URL, replaces the app and
needs ``--force``.

*********************
 Expose injected apps
*********************

Injected packages do not add their entry points to your ``PATH`` by default. Use ``--include-apps`` to expose them:

.. code-block:: console

    $ pipx inject ipython black --include-apps

``--include-deps`` exposes apps and manual pages from every dependency. Use ``--include-resources-from PACKAGE`` to
expose one dependency, repeating it to select more. Both options imply ``--include-apps``. As with ``pipx install``, a
package with no app to expose fails the inject and leaves the environment as it was.

.. code-block:: console

    $ pipx inject robotframework-keyta robotframework-browser-batteries --include-resources-from robotframework-browser

For exposing apps from an already-installed environment, see :doc:`expose-apps`.

************
 Other flags
************

- ``--force`` / ``-f`` reinstalls the package even when it is already injected.
- ``--editable`` / ``-e`` installs the package in editable (development) mode.
- ``--with-suffix`` gives the injected package's apps the environment's suffix (injecting ``black`` into
  ``ipython_3.11`` exposes ``black_3.11``).
- ``--pip-args`` passes extra arguments to `pip <https://pip.pypa.io/>`__ (for example ``--pip-args='--no-cache-dir'``).
- ``--index-url`` / ``-i`` sets the package index URL for this inject.
- ``--system-site-packages`` only prints a warning; the environment keeps the setting ``pipx install`` gave it.

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

.. code-block:: console

    $ pipx list --include-injected

The injected packages appear under their host environment.
