| @@ -0,0 +1,104 @@ | ||
| # Getting Started | ||
|
|
||
| To get started with using pip, you should [install Python] on your system. | ||
|
|
||
| [install Python]: https://realpython.com/installing-python/ | ||
|
|
||
| ## Ensure you have a working pip | ||
|
|
||
| As a first step, you should check that you have a working Python with pip | ||
| installed. This can be done by running the following commands and making | ||
| sure that the output looks similar. | ||
|
|
||
| ```{pip-cli} | ||
| $ python --version | ||
| Python 3.N.N | ||
| $ pip --version | ||
| pip X.Y.Z from ... (python 3.N.N) | ||
| ``` | ||
|
|
||
| If that worked, congratulations! You have a working pip in your environment. | ||
|
|
||
| If you got output that does not look like the sample above, please read | ||
| the {doc}`installation` page. It provides guidance on how to install pip | ||
| within a Python environment that doesn't have it. | ||
|
|
||
| ## Common tasks | ||
|
|
||
| ### Install a package | ||
|
|
||
| ```{pip-cli} | ||
| $ pip install sampleproject | ||
| [...] | ||
| Successfully installed sampleproject | ||
| ``` | ||
|
|
||
| By default, pip will fetch packages from [Python Package Index][PyPI], a | ||
| repository of software for the Python programming language where anyone can | ||
| upload packages. | ||
|
|
||
| [PyPI]: https://pypi.org/ | ||
|
|
||
| ### Install a package from GitHub | ||
|
|
||
| ```{pip-cli} | ||
| $ pip install git+https://github.com/pypa/sampleproject.git@main | ||
| [...] | ||
| Successfully installed sampleproject | ||
| ``` | ||
|
|
||
| See {doc}`topics/vcs-support` for more information about this syntax. | ||
|
|
||
| ### Install a package from a distribution file | ||
|
|
||
| pip can install directly from distribution files as well. They come in 2 forms: | ||
|
|
||
| - {term}`source distribution <Source Distribution (or "sdist")>` (usually shortened to "sdist") | ||
| - {term}`wheel distribution <Wheel>` (usually shortened to "wheel") | ||
|
|
||
| ```{pip-cli} | ||
| $ pip install sampleproject-1.0.tar.gz | ||
| [...] | ||
| Successfully installed sampleproject | ||
| $ pip install sampleproject-1.0-py3-none-any.whl | ||
| [...] | ||
| Successfully installed sampleproject | ||
| ``` | ||
|
|
||
| ### Install multiple packages using a requirements file | ||
|
|
||
| Many Python projects use {file}`requirements.txt` files, to specify the | ||
| list of packages that need to be installed for the project to run. To install | ||
| the packages listed in that file, you can run: | ||
|
|
||
| ```{pip-cli} | ||
| $ pip install -r requirements.txt | ||
| [...] | ||
| Successfully installed sampleproject | ||
| ``` | ||
|
|
||
| ### Upgrade a package | ||
|
|
||
| ```{pip-cli} | ||
| $ pip install --upgrade sampleproject | ||
| Uninstalling sampleproject: | ||
| [...] | ||
| Proceed (y/n)? y | ||
| Successfully uninstalled sampleproject | ||
| ``` | ||
|
|
||
| ### Uninstall a package | ||
|
|
||
| ```{pip-cli} | ||
| $ pip uninstall sampleproject | ||
| Uninstalling sampleproject: | ||
| [...] | ||
| Proceed (y/n)? y | ||
| Successfully uninstalled sampleproject | ||
| ``` | ||
|
|
||
| ## Next Steps | ||
|
|
||
| It is recommended to learn about what virtual environments are and how to use | ||
| them. This is covered in the ["Installing Packages"](pypug:tutorials/installing-packages) | ||
| tutorial on packaging.python.org. |
| @@ -0,0 +1,80 @@ | ||
| # Installation | ||
|
|
||
| Usually, pip is automatically installed if you are: | ||
|
|
||
| - working in a | ||
| {ref}`virtual environment <pypug:Creating and using Virtual Environments>` | ||
| - using Python downloaded from [python.org](https://www.python.org) | ||
| - using Python that has not been modified by a redistributor to remove | ||
| {mod}`ensurepip` | ||
|
|
||
| ## Supported Methods | ||
|
|
||
| If your Python environment does not have pip installed, there are 2 mechanisms | ||
| to install pip supported directly by pip's maintainers: | ||
|
|
||
| - [`ensurepip`](#ensurepip) | ||
| - [`get-pip.py`](#get-pip-py) | ||
|
|
||
| ### `ensurepip` | ||
|
|
||
| Python comes with an {mod}`ensurepip` module[^python], which can install pip in | ||
| a Python environment. | ||
|
|
||
| ```{pip-cli} | ||
| $ python -m ensurepip --upgrade | ||
| ``` | ||
|
|
||
| More details about how {mod}`ensurepip` works and how it can be used, is | ||
| available in the standard library documentation. | ||
|
|
||
| ### `get-pip.py` | ||
|
|
||
| This is a Python script that uses some bootstrapping logic to install | ||
| pip. | ||
|
|
||
| - Download the script, from <https://bootstrap.pypa.io/get-pip.py>. | ||
| - Open a terminal/command prompt, `cd` to the folder containing the | ||
| `get-pip.py` file and run: | ||
|
|
||
| ```{pip-cli} | ||
| $ python get-pip.py | ||
| ``` | ||
|
|
||
| More details about this script can be found in [pypa/get-pip]'s README. | ||
|
|
||
| [pypa/get-pip]: https://github.com/pypa/get-pip | ||
|
|
||
| ## Alternative Methods | ||
|
|
||
| Depending on how you installed Python, there might be other mechanisms | ||
| available to you for installing pip such as | ||
| {ref}`using Linux package managers <pypug:installing pip/setuptools/wheel with linux package managers>`. | ||
|
|
||
| These mechanisms are provided by redistributors of pip, who may have modified | ||
| pip to change its behaviour. This has been a frequent source of user confusion, | ||
| since it causes a mismatch between documented behaviour in this documentation | ||
| and how pip works after those modifications. | ||
|
|
||
| If you face issues when using Python and pip installed using these mechanisms, | ||
| it is recommended to request for support from the relevant provider (eg: Linux | ||
| distro community, cloud provider support channels, etc). | ||
|
|
||
| (compatibility-requirements)= | ||
|
|
||
| ## Compatibility | ||
|
|
||
| The current version of pip works on: | ||
|
|
||
| - Windows, Linux and MacOS. | ||
| - CPython 3.6, 3.7, 3.8, 3.9 and latest PyPy3. | ||
|
|
||
| pip is tested to work on the latest patch version of the Python interpreter, | ||
| for each of the minor versions listed above. Previous patch versions are | ||
| supported on a best effort approach. | ||
|
|
||
| pip's maintainers do not provide support for users on older versions of Python, | ||
| and these users should request for support from the relevant provider | ||
| (eg: Linux distro community, cloud provider support channels, etc). | ||
|
|
||
| [^python]: The `ensurepip` module was added to the Python standard library in Python 3.4. |
| @@ -1,230 +1,11 @@ | ||
| .. _`Installation`: | ||
| :orphan: | ||
|
|
||
| ============ | ||
| Installation | ||
| ============ | ||
| .. meta:: | ||
|
|
||
| Do I need to install pip? | ||
| ========================= | ||
| :http-equiv=refresh: 3; url=../installation/ | ||
|
|
||
| pip is already installed if you are using Python 2 >=2.7.9 or Python 3 >=3.4 | ||
| downloaded from `python.org <https://www.python.org>`_ or if you are working | ||
| in a :ref:`Virtual Environment <pypug:Creating and using Virtual Environments>` | ||
| created by :ref:`pypug:virtualenv` or :ref:`venv <pypug:venv>`. Just make sure | ||
| to :ref:`upgrade pip <Upgrading pip>`. | ||
| This page has moved | ||
| =================== | ||
|
|
||
| Use the following command to check whether pip is installed: | ||
|
|
||
| .. tab:: Unix/macOS | ||
|
|
||
| .. code-block:: console | ||
|
|
||
| $ python -m pip --version | ||
| pip X.Y.Z from .../site-packages/pip (python X.Y) | ||
|
|
||
| .. tab:: Windows | ||
|
|
||
| .. code-block:: console | ||
|
|
||
| C:\> py -m pip --version | ||
| pip X.Y.Z from ...\site-packages\pip (python X.Y) | ||
|
|
||
| Using Linux Package Managers | ||
| ============================ | ||
|
|
||
| .. warning:: | ||
|
|
||
| If you installed Python from a package manager on Linux, you should always | ||
| install pip for that Python installation using the same source. | ||
|
|
||
| See `pypug:Installing pip/setuptools/wheel with Linux Package Managers <https://packaging.python.org/guides/installing-using-linux-tools/>`_ | ||
| in the Python Packaging User Guide. | ||
|
|
||
| Here are ways to contact a few Linux package maintainers if you run into | ||
| problems: | ||
|
|
||
| * `Deadsnakes PPA <https://github.com/deadsnakes/issues>`_ | ||
| * `Debian Python Team <https://wiki.debian.org/Teams/PythonTeam>`_ (for general | ||
| issues related to ``apt``) | ||
| * `Red Hat Bugzilla <https://bugzilla.redhat.com/>`_ | ||
|
|
||
| pip developers do not have control over how Linux distributions handle pip | ||
| installations, and are unable to provide solutions to related issues in | ||
| general. | ||
|
|
||
| Using ensurepip | ||
| =============== | ||
|
|
||
| Python >=3.4 can self-bootstrap pip with the built-in | ||
| :ref:`ensurepip <pypug:ensurepip>` module. Refer to the standard library | ||
| documentation for more details. Make sure to :ref:`upgrade pip <Upgrading pip>` | ||
| after ``ensurepip`` installs pip. | ||
|
|
||
| See the `Using Linux Package Managers`_ section if your Python reports | ||
| ``No module named ensurepip`` on Debian and derived systems (e.g. Ubuntu). | ||
|
|
||
|
|
||
| .. _`get-pip`: | ||
|
|
||
| Installing with get-pip.py | ||
| ========================== | ||
|
|
||
| .. warning:: | ||
|
|
||
| Be cautious if you are using a Python install that is managed by your operating | ||
| system or another package manager. ``get-pip.py`` does not coordinate with | ||
| those tools, and may leave your system in an inconsistent state. | ||
|
|
||
| To manually install pip, securely [1]_ download ``get-pip.py`` by following | ||
| this link: `get-pip.py | ||
| <https://bootstrap.pypa.io/get-pip.py>`_. Alternatively, use ``curl``:: | ||
|
|
||
| curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py | ||
|
|
||
| Then run the following command in the folder where you | ||
| have downloaded ``get-pip.py``: | ||
|
|
||
| .. tab:: Unix/macOS | ||
|
|
||
| .. code-block:: shell | ||
| python get-pip.py | ||
| .. tab:: Windows | ||
|
|
||
| .. code-block:: shell | ||
| py get-pip.py | ||
| ``get-pip.py`` also installs :ref:`pypug:setuptools` [2]_ and :ref:`pypug:wheel` | ||
| if they are not already. :ref:`pypug:setuptools` is required to install | ||
| :term:`source distributions <pypug:Source Distribution (or "sdist")>`. Both are | ||
| required in order to build a :ref:`Wheel cache` (which improves installation | ||
| speed), although neither are required to install pre-built :term:`wheels | ||
| <pypug:Wheel>`. | ||
|
|
||
| .. note:: | ||
|
|
||
| The get-pip.py script is supported on the same python version as pip. | ||
| For the now unsupported Python 2.6, alternate script is available | ||
| `here <https://bootstrap.pypa.io/2.6/get-pip.py>`__. | ||
|
|
||
|
|
||
| get-pip.py options | ||
| ------------------ | ||
|
|
||
| .. option:: --no-setuptools | ||
|
|
||
| If set, do not attempt to install :ref:`pypug:setuptools` | ||
|
|
||
| .. option:: --no-wheel | ||
|
|
||
| If set, do not attempt to install :ref:`pypug:wheel` | ||
|
|
||
|
|
||
| ``get-pip.py`` allows :ref:`pip install options <pip | ||
| install Options>` and the :ref:`general options <General Options>`. Below are | ||
| some examples: | ||
|
|
||
| Install from local copies of pip and setuptools: | ||
|
|
||
| .. tab:: Unix/macOS | ||
|
|
||
| .. code-block:: shell | ||
| python get-pip.py --no-index --find-links=/local/copies | ||
| .. tab:: Windows | ||
|
|
||
| .. code-block:: shell | ||
| py get-pip.py --no-index --find-links=/local/copies | ||
| Install to the user site [3]_: | ||
|
|
||
| .. tab:: Unix/macOS | ||
|
|
||
| .. code-block:: shell | ||
| python get-pip.py --user | ||
| .. tab:: Windows | ||
|
|
||
| .. code-block:: shell | ||
| py get-pip.py --user | ||
| Install behind a proxy: | ||
|
|
||
| .. tab:: Unix/macOS | ||
|
|
||
| .. code-block:: shell | ||
| python get-pip.py --proxy="http://[user:passwd@]proxy.server:port" | ||
| .. tab:: Windows | ||
|
|
||
| .. code-block:: shell | ||
| py get-pip.py --proxy="http://[user:passwd@]proxy.server:port" | ||
| ``get-pip.py`` can also be used to install a specified combination of ``pip``, | ||
| ``setuptools``, and ``wheel`` using the same requirements syntax as pip: | ||
|
|
||
| .. tab:: Unix/macOS | ||
|
|
||
| .. code-block:: shell | ||
| python get-pip.py pip==9.0.2 wheel==0.30.0 setuptools==28.8.0 | ||
| .. tab:: Windows | ||
|
|
||
| .. code-block:: shell | ||
| py get-pip.py pip==9.0.2 wheel==0.30.0 setuptools==28.8.0 | ||
| .. _`Upgrading pip`: | ||
|
|
||
| Upgrading pip | ||
| ============= | ||
|
|
||
| .. tab:: Unix/macOS | ||
|
|
||
| .. code-block:: shell | ||
| python -m pip install -U pip | ||
| .. tab:: Windows | ||
|
|
||
| .. code-block:: shell | ||
| py -m pip install -U pip | ||
| .. _compatibility-requirements: | ||
|
|
||
| Python and OS Compatibility | ||
| =========================== | ||
|
|
||
| pip works with CPython versions 3.6, 3.7, 3.8, 3.9 and also PyPy. | ||
|
|
||
| This means pip works on the latest patch version of each of these minor | ||
| versions. Previous patch versions are supported on a best effort approach. | ||
|
|
||
| pip works on Unix/Linux, macOS, and Windows. | ||
|
|
||
|
|
||
| ---- | ||
|
|
||
| .. [1] "Secure" in this context means using a modern browser or a | ||
| tool like ``curl`` that verifies SSL certificates when downloading from | ||
| https URLs. | ||
| .. [2] Beginning with pip v1.5.1, ``get-pip.py`` stopped requiring setuptools to | ||
| be installed first. | ||
| .. [3] The pip developers are considering making ``--user`` the default for all | ||
| installs, including ``get-pip.py`` installs of pip, but at this time, | ||
| ``--user`` installs for pip itself, should not be considered to be fully | ||
| tested or endorsed. For discussion, see `Issue 1668 | ||
| <https://github.com/pypa/pip/issues/1668>`_. | ||
| You should be redirected automatically in 3 seconds. If that didn't | ||
| work, here's a link: :doc:`installation` |
| @@ -1,136 +1,11 @@ | ||
| ========== | ||
| Quickstart | ||
| ========== | ||
| :orphan: | ||
|
|
||
| First, :doc:`install pip <installing>`. | ||
| .. meta:: | ||
|
|
||
| Install a package from `PyPI`_: | ||
| :http-equiv=refresh: 3; url=../getting-started/ | ||
|
|
||
| .. tab:: Unix/macOS | ||
| This page has moved | ||
| =================== | ||
|
|
||
| .. code-block:: console | ||
|
|
||
| $ python -m pip install SomePackage | ||
| [...] | ||
| Successfully installed SomePackage | ||
|
|
||
| .. tab:: Windows | ||
|
|
||
| .. code-block:: console | ||
|
|
||
| C:\> py -m pip install SomePackage | ||
| [...] | ||
| Successfully installed SomePackage | ||
|
|
||
|
|
||
| Install a package that's already been downloaded from `PyPI`_ or | ||
| obtained from elsewhere. This is useful if the target machine does not have a | ||
| network connection: | ||
|
|
||
| .. tab:: Unix/macOS | ||
|
|
||
| .. code-block:: console | ||
|
|
||
| $ python -m pip install SomePackage-1.0-py2.py3-none-any.whl | ||
| [...] | ||
| Successfully installed SomePackage | ||
|
|
||
| .. tab:: Windows | ||
|
|
||
| .. code-block:: console | ||
|
|
||
| C:\> py -m pip install SomePackage-1.0-py2.py3-none-any.whl | ||
| [...] | ||
| Successfully installed SomePackage | ||
|
|
||
| Show what files were installed: | ||
|
|
||
| .. tab:: Unix/macOS | ||
|
|
||
| .. code-block:: console | ||
|
|
||
| $ python -m pip show --files SomePackage | ||
| Name: SomePackage | ||
| Version: 1.0 | ||
| Location: /my/env/lib/pythonx.x/site-packages | ||
| Files: | ||
| ../somepackage/__init__.py | ||
| [...] | ||
|
|
||
| .. tab:: Windows | ||
|
|
||
| .. code-block:: console | ||
|
|
||
| C:\> py -m pip show --files SomePackage | ||
| Name: SomePackage | ||
| Version: 1.0 | ||
| Location: /my/env/lib/pythonx.x/site-packages | ||
| Files: | ||
| ../somepackage/__init__.py | ||
| [...] | ||
|
|
||
| List what packages are outdated: | ||
|
|
||
| .. tab:: Unix/macOS | ||
|
|
||
| .. code-block:: console | ||
|
|
||
| $ python -m pip list --outdated | ||
| SomePackage (Current: 1.0 Latest: 2.0) | ||
|
|
||
| .. tab:: Windows | ||
|
|
||
| .. code-block:: console | ||
|
|
||
| C:\> py -m pip list --outdated | ||
| SomePackage (Current: 1.0 Latest: 2.0) | ||
|
|
||
| Upgrade a package: | ||
|
|
||
| .. tab:: Unix/macOS | ||
|
|
||
| .. code-block:: console | ||
|
|
||
| $ python -m pip install --upgrade SomePackage | ||
| [...] | ||
| Found existing installation: SomePackage 1.0 | ||
| Uninstalling SomePackage: | ||
| Successfully uninstalled SomePackage | ||
| Running setup.py install for SomePackage | ||
| Successfully installed SomePackage | ||
|
|
||
| .. tab:: Windows | ||
|
|
||
| .. code-block:: console | ||
|
|
||
| C:\> py -m pip install --upgrade SomePackage | ||
| [...] | ||
| Found existing installation: SomePackage 1.0 | ||
| Uninstalling SomePackage: | ||
| Successfully uninstalled SomePackage | ||
| Running setup.py install for SomePackage | ||
| Successfully installed SomePackage | ||
|
|
||
| Uninstall a package: | ||
|
|
||
| .. tab:: Unix/macOS | ||
|
|
||
| .. code-block:: console | ||
|
|
||
| $ python -m pip uninstall SomePackage | ||
| Uninstalling SomePackage: | ||
| /my/env/lib/pythonx.x/site-packages/somepackage | ||
| Proceed (y/n)? y | ||
| Successfully uninstalled SomePackage | ||
|
|
||
| .. tab:: Windows | ||
|
|
||
| .. code-block:: console | ||
|
|
||
| C:\> py -m pip uninstall SomePackage | ||
| Uninstalling SomePackage: | ||
| /my/env/lib/pythonx.x/site-packages/somepackage | ||
| Proceed (y/n)? y | ||
| Successfully uninstalled SomePackage | ||
|
|
||
| .. _PyPI: https://pypi.org/ | ||
| You should be redirected automatically in 3 seconds. If that didn't | ||
| work, here's a link: :doc:`getting-started` |
| @@ -0,0 +1,83 @@ | ||
| # Authentication | ||
|
|
||
| ## Basic HTTP authentication | ||
|
|
||
| pip supports basic HTTP-based authentication credentials. This is done by | ||
| providing the username (and optionally password) in the URL: | ||
|
|
||
| ``` | ||
| https://username:password@pypi.company.com/simple | ||
| ``` | ||
|
|
||
| For indexes that only require single-part authentication tokens, provide the | ||
| token as the "username" and do not provide a password: | ||
|
|
||
| ``` | ||
| https://0123456789abcdef@pypi.company.com/simple | ||
| ``` | ||
|
|
||
| ### Percent-encoding special characters | ||
|
|
||
| ```{versionadded} 10.0 | ||
| ``` | ||
|
|
||
| Certain special characters are not valid in the credential part of a URL. | ||
| If the user or password part of your login credentials contain any of these | ||
| [special characters][reserved-chars], then they must be percent-encoded. As an | ||
| example, for a user with username `user` and password `he//o` accessing a | ||
| repository at `pypi.company.com/simple`, the URL with credentials would look | ||
| like: | ||
|
|
||
| ``` | ||
| https://user:he%2F%2Fo@pypi.company.com/simple | ||
| ``` | ||
|
|
||
| [reserved-chars]: https://en.wikipedia.org/wiki/Percent-encoding#Percent-encoding_reserved_characters | ||
|
|
||
| ## netrc support | ||
|
|
||
| pip supports loading credentials from a user's `.netrc` file. If no credentials | ||
| are part of the URL, pip will attempt to get authentication credentials for the | ||
| URL's hostname from the user's `.netrc` file. This behaviour comes from the | ||
| underlying use of {pypi}`requests`, which in turn delegates it to the | ||
| [Python standard library's `netrc` module][netrc-std-lib]. | ||
|
|
||
| ```{note} | ||
| As mentioned in the [standard library documentation for netrc][netrc-std-lib], | ||
| only ASCII characters are allowed in `.netrc` files. Whitespace and | ||
| non-printable characters are not allowed in passwords. | ||
| ``` | ||
|
|
||
| Below is an example `.netrc`, for the host `example.com`, with a user named | ||
| `daniel`, using the password `qwerty`: | ||
|
|
||
| ``` | ||
| machine example.com | ||
| login daniel | ||
| password qwerty | ||
| ``` | ||
|
|
||
| More information about the `.netrc` file format can be found in the GNU [`ftp` | ||
| man pages][netrc-docs]. | ||
|
|
||
| [netrc-docs]: https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html | ||
| [netrc-std-lib]: https://docs.python.org/3/library/netrc.html | ||
|
|
||
| ## Keyring Support | ||
|
|
||
| pip supports loading credentials stored in your keyring using the | ||
| {pypi}`keyring` library. | ||
|
|
||
| ```bash | ||
| $ pip install keyring # install keyring from PyPI | ||
| $ echo "your-password" | keyring set pypi.company.com your-username | ||
| $ pip install your-package --index-url https://pypi.company.com/ | ||
| ``` | ||
|
|
||
| Note that `keyring` (the Python package) needs to be installed separately from | ||
| pip. This can create a bootstrapping issue if you need the credentials stored in | ||
| the keyring to download and install keyring. | ||
|
|
||
| It is, thus, expected that users that wish to use pip's keyring support have | ||
| some mechanism for downloading and installing {pypi}`keyring` in their Python | ||
| environment. |
| @@ -0,0 +1,86 @@ | ||
| # Caching | ||
|
|
||
| ```{versionadded} 6.0 | ||
| ``` | ||
|
|
||
| pip provides an on-by-default caching, designed to reduce the amount of time | ||
| spent on duplicate downloads and builds. | ||
|
|
||
| ## What is cached | ||
|
|
||
| ### HTTP responses | ||
|
|
||
| This cache functions like a web browser cache. | ||
|
|
||
| When making any HTTP request, pip will first check its local cache to determine | ||
| if it has a suitable response stored for that request which has not expired. If | ||
| it does then it returns that response and doesn't re-download the content. | ||
|
|
||
| If it has a response stored but it has expired, then it will attempt to make a | ||
| conditional request to refresh the cache which will either return an empty | ||
| response telling pip to simply use the cached item (and refresh the expiration | ||
| timer) or it will return a whole new response which pip can then store in the | ||
| cache. | ||
|
|
||
| While this cache attempts to minimize network activity, it does not prevent | ||
| network access altogether. If you want a local install solution that | ||
| circumvents accessing PyPI, see {ref}`Installing from local packages`. | ||
|
|
||
| ### Locally built wheels | ||
|
|
||
| pip attempts to use wheels from its local wheel cache whenever possible. | ||
|
|
||
| This means that if there is a cached wheel for the same version of a specific | ||
| package name, pip will use that wheel instead of rebuilding the project. | ||
|
|
||
| When no wheels are found for a source distribution, pip will attempt to build a | ||
| wheel using the package's build system. If the build is successful, this wheel | ||
| is added to the cache and used in subsequent installs for the same package | ||
| version. | ||
|
|
||
| ```{versionchanged} 20.0 | ||
| pip now caches wheels when building from an immutable Git reference | ||
| (i.e. a commit hash). | ||
| ``` | ||
|
|
||
| ## Avoiding caching | ||
|
|
||
| pip tries to use its cache whenever possible, and it is designed do the right | ||
| thing by default. | ||
|
|
||
| In some cases, pip's caching behaviour can be undesirable. As an example, if you | ||
| have package with optional C extensions, that generates a pure Python wheel | ||
| when the C extension can’t be built, pip will use that cached wheel even when | ||
| you later invoke it from an environment that could have built those optional C | ||
| extensions. This is because pip is seeing a cached wheel for that matches the | ||
| package being built, and pip assumes that the result of building a package from | ||
| a package index is deterministic. | ||
|
|
||
| The recommended approach for dealing with these situations is to directly | ||
| install from a source distribution instead of letting pip auto-discover the | ||
| package when it is trying to install. Installing directly from a source | ||
| distribution will make pip build a wheel, regardless of whether there is a | ||
| matching cached wheel. This usually means doing something like: | ||
|
|
||
| ```{pip-cli} | ||
| $ pip download sampleproject==1.0.0 --no-binary :all: | ||
| $ pip install sampleproject-1.0.0.tar.gz | ||
| ``` | ||
|
|
||
| It is also a good idea to remove the offending cached wheel using the | ||
| {ref}`pip cache` command. | ||
|
|
||
| ## Cache management | ||
|
|
||
| The {ref}`pip cache` command can be used to manage pip's cache. | ||
|
|
||
| The exact filesystem structure of pip's cache is considered to be an | ||
| implementation detail and may change between any two versions of pip. | ||
|
|
||
| ## Disabling caching | ||
|
|
||
| pip's caching behaviour is disabled by passing the ``--no-cache-dir`` option. | ||
|
|
||
| It is, however, recommended to **NOT** disable pip's caching. Doing so can | ||
| significantly slow down pip (due to repeated operations and package builds) | ||
| and result in significantly more network usage. |
| @@ -0,0 +1,226 @@ | ||
| # Configuration | ||
|
|
||
| pip allows a user to change its behaviour via 3 mechanisms: | ||
|
|
||
| - command line options | ||
| - environment variables | ||
| - configuration files | ||
|
|
||
| This page explains how the configuration files and environment variables work, | ||
| and how they are related to pip's various command line options. | ||
|
|
||
| ## Configuration Files | ||
|
|
||
| Configuration files can change the default values for command line option. | ||
| They are written using a standard INI style configuration files. | ||
|
|
||
| pip has 3 "levels" of configuration files: | ||
|
|
||
| - `global`: system-wide configuration file, shared across users. | ||
| - `user`: per-user configuration file. | ||
| - `site`: per-environment configuration file; i.e. per-virtualenv. | ||
|
|
||
| ### Location | ||
|
|
||
| pip's configuration files are located in fairly standard locations. This | ||
| location is different on different operating systems, and has some additional | ||
| complexity for backwards compatibility reasons. | ||
|
|
||
| ```{tab} Unix | ||
| Global | ||
| : {file}`/etc/pip.conf` | ||
| Alternatively, it may be in a "pip" subdirectory of any of the paths set | ||
| in the environment variable `XDG_CONFIG_DIRS` (if it exists), for | ||
| example {file}`/etc/xdg/pip/pip.conf`. | ||
| User | ||
| : {file}`$HOME/.config/pip/pip.conf`, which respects the `XDG_CONFIG_HOME` environment variable. | ||
| The legacy "per-user" configuration file is also loaded, if it exists: {file}`$HOME/.pip/pip.conf`. | ||
| Site | ||
| : {file}`$VIRTUAL_ENV/pip.conf` | ||
| ``` | ||
|
|
||
| ```{tab} MacOS | ||
| Global | ||
| : {file}`/Library/Application Support/pip/pip.conf` | ||
| User | ||
| : {file}`$HOME/Library/Application Support/pip/pip.conf` | ||
| if directory `$HOME/Library/Application Support/pip` exists | ||
| else {file}`$HOME/.config/pip/pip.conf` | ||
| The legacy "per-user" configuration file is also loaded, if it exists: {file}`$HOME/.pip/pip.conf`. | ||
| Site | ||
| : {file}`$VIRTUAL_ENV/pip.conf` | ||
| ``` | ||
|
|
||
| ```{tab} Windows | ||
| Global | ||
| : * On Windows 7 and later: {file}`C:\\ProgramData\\pip\\pip.ini` | ||
| (hidden but writeable) | ||
| * On Windows Vista: Global configuration is not supported. | ||
| * On Windows XP: | ||
| {file}`C:\\Documents and Settings\\All Users\\Application Data\\pip\\pip.ini` | ||
| User | ||
| : {file}`%APPDATA%\\pip\\pip.ini` | ||
| The legacy "per-user" configuration file is also loaded, if it exists: {file}`%HOME%\\pip\\pip.ini` | ||
| Site | ||
| : {file}`%VIRTUAL_ENV%\\pip.ini` | ||
| ``` | ||
|
|
||
| ### `PIP_CONFIG_FILE` | ||
|
|
||
| Additionally, the environment variable `PIP_CONFIG_FILE` can be used to specify | ||
| a configuration file that's loaded first, and whose values are overridden by | ||
| the values set in the aforementioned files. Setting this to {any}`os.devnull` | ||
| disables the loading of _all_ configuration files. | ||
|
|
||
| ### Loading order | ||
|
|
||
| When multiple configuration files are found, pip combines them in the following | ||
| order: | ||
|
|
||
| - `PIP_CONFIG_FILE`, if given. | ||
| - Global | ||
| - User | ||
| - Site | ||
|
|
||
| Each file read overrides any values read from previous files, so if the | ||
| global timeout is specified in both the global file and the per-user file | ||
| then the latter value will be used. | ||
|
|
||
| ### Naming | ||
|
|
||
| The names of the settings are derived from the long command line option. | ||
|
|
||
| As an example, if you want to use a different package index (`--index-url`) and | ||
| set the HTTP timeout (`--default-timeout`) to 60 seconds, your config file would | ||
| look like this: | ||
|
|
||
| ```ini | ||
| [global] | ||
| timeout = 60 | ||
| index-url = https://download.zope.org/ppix | ||
| ``` | ||
|
|
||
| ### Per-command section | ||
|
|
||
| Each subcommand can be configured optionally in its own section. This overrides | ||
| the global setting with the same name. | ||
|
|
||
| As an example, if you want to decrease the `timeout` to `10` seconds when | ||
| running the {ref}`pip freeze`, and use `60` seconds for all other commands: | ||
|
|
||
| ```ini | ||
| [global] | ||
| timeout = 60 | ||
| [freeze] | ||
| timeout = 10 | ||
| ``` | ||
|
|
||
| ### Boolean options | ||
|
|
||
| Boolean options like `--ignore-installed` or `--no-dependencies` can be set | ||
| like this: | ||
|
|
||
| ```ini | ||
| [install] | ||
| ignore-installed = true | ||
| no-dependencies = yes | ||
| ``` | ||
|
|
||
| To enable the boolean options `--no-compile`, `--no-warn-script-location` and | ||
| `--no-cache-dir`, falsy values have to be used: | ||
|
|
||
| ```ini | ||
| [global] | ||
| no-cache-dir = false | ||
| [install] | ||
| no-compile = no | ||
| no-warn-script-location = false | ||
| ``` | ||
|
|
||
| ### Repeatable options | ||
|
|
||
| For options which can be repeated like `--verbose` and `--quiet`, a | ||
| non-negative integer can be used to represent the level to be specified: | ||
|
|
||
| ```ini | ||
| [global] | ||
| quiet = 0 | ||
| verbose = 2 | ||
| ``` | ||
|
|
||
| It is possible to append values to a section within a configuration file. This | ||
| is applicable to appending options like `--find-links` or `--trusted-host`, | ||
| which can be written on multiple lines: | ||
|
|
||
| ```ini | ||
| [global] | ||
| find-links = | ||
| http://download.example.com | ||
| [install] | ||
| find-links = | ||
| http://mirror1.example.com | ||
| http://mirror2.example.com | ||
| trusted-host = | ||
| mirror1.example.com | ||
| mirror2.example.com | ||
| ``` | ||
|
|
||
| This enables users to add additional values in the order of entry for such | ||
| command line arguments. | ||
|
|
||
| ## Environment Variables | ||
|
|
||
| pip's command line options can be set with environment variables using the | ||
| format `PIP_<UPPER_LONG_NAME>` . Dashes (`-`) have to be replaced with | ||
| underscores (`_`). | ||
|
|
||
| - `PIP_DEFAULT_TIMEOUT=60` is the same as `--default-timeout=60` | ||
| - ``` | ||
| PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com" | ||
| ``` | ||
|
|
||
| is the same as | ||
|
|
||
| ``` | ||
| --find-links=http://mirror1.example.com --find-links=http://mirror2.example.com | ||
| ``` | ||
|
|
||
| Repeatable options that do not take a value (such as `--verbose`) can be | ||
| specified using the number of repetitions: | ||
|
|
||
| - `PIP_VERBOSE=3` is the same as `pip install -vvv` | ||
|
|
||
| ```{note} | ||
| Environment variables set to an empty string (like with `export X=` on Unix) will **not** be treated as false. | ||
| Use `no`, `false` or `0` instead. | ||
| ``` | ||
|
|
||
| ## Precedence / Override order | ||
|
|
||
| Command line options have override environment variables, which override the | ||
| values in a configuration file. Within the configuration file, values in | ||
| command-specific sections over values in the global section. | ||
|
|
||
| Examples: | ||
|
|
||
| - `--host=foo` overrides `PIP_HOST=foo` | ||
| - `PIP_HOST=foo` overrides a config file with `[global] host = foo` | ||
| - A command specific section in the config file `[<command>] host = bar` | ||
| overrides the option with same name in the `[global]` config file section. |
| @@ -0,0 +1,108 @@ | ||
| # Dependency Resolution | ||
|
|
||
| pip is capable of determining and installing the dependencies of packages. The | ||
| process of determining which version of a dependency to install is known as | ||
| dependency resolution. This behaviour can be disabled by passing | ||
| {any}`--no-deps` to {any}`pip install`. | ||
|
|
||
| ## How it works | ||
|
|
||
| When a user does a `pip install` (e.g. `pip install tea`), pip needs to work | ||
| out the package's dependencies (e.g. `spoon`, `hot-water`, `tea-leaves` etc.) | ||
| and what the versions of each of those dependencies it should install. | ||
|
|
||
| At the start of a `pip install` run, pip does not have all the dependency | ||
| information of the requested packages. It needs to work out the dependencies | ||
| of the requested packages, the dependencies of those dependencies, and so on. | ||
| Over the course of the dependency resolution process, pip will need to download | ||
| distribution files of the packages which are used to get the dependencies of a | ||
| package. | ||
|
|
||
| ## Backtracking | ||
|
|
||
| ```{versionchanged} 20.3 | ||
| pip's dependency resolver is now capable of backtracking. | ||
| ``` | ||
|
|
||
| During dependency resolution, pip needs to make assumptions about the package | ||
| versions it needs to install and, later, check these assumptions were not | ||
| incorrect. When pip finds that an assumption it made earlier is incorrect, it | ||
| has to backtrack, which means also discarding some of the work that has already | ||
| been done, and going back to choose another path. | ||
|
|
||
| This can look like pip downloading multiple versions of the same package, | ||
| since pip explicitly presents each download to the user. The backtracking of | ||
| choices made during is not unexpected behaviour or a bug. It is part of how | ||
| dependency resolution for Python packages works. | ||
|
|
||
| ````{admonition} Example | ||
| The user requests `pip install tea`. The package `tea` declares a dependency on | ||
| `hot-water`, `spoon`, `cup`, amongst others. | ||
| pip starts by picking the most recent version of `tea` and get the list of | ||
| dependencies of that version of `tea`. It will then repeat the process for | ||
| those packages, picking the most recent version of `spoon` and then `cup`. Now, | ||
| pip notices that the version of `cup` it has chosen is not compatible with the | ||
| version of `spoon` it has chosen. Thus, pip will "go back" (backtrack) and try | ||
| to use another version of `cup`. If it is successful, it will continue onto the | ||
| next package (like `sugar`). Otherwise, it will continue to backtrack on `cup` | ||
| until it finds a version of `cup` that is compatible with all the other | ||
| packages. | ||
| This can look like: | ||
| ```console | ||
| $ pip install tea | ||
| Collecting tea | ||
| Downloading tea-1.9.8-py2.py3-none-any.whl (346 kB) | ||
| |████████████████████████████████| 346 kB 10.4 MB/s | ||
| Collecting spoon==2.27.0 | ||
| Downloading spoon-2.27.0-py2.py3-none-any.whl (312 kB) | ||
| |████████████████████████████████| 312 kB 19.2 MB/s | ||
| Collecting cup>=1.6.0 | ||
| Downloading cup-3.22.0-py2.py3-none-any.whl (397 kB) | ||
| |████████████████████████████████| 397 kB 28.2 MB/s | ||
| INFO: pip is looking at multiple versions of this package to determine | ||
| which version is compatible with other requirements. | ||
| This could take a while. | ||
| Downloading cup-3.21.0-py2.py3-none-any.whl (395 kB) | ||
| |████████████████████████████████| 395 kB 27.0 MB/s | ||
| Downloading cup-3.20.0-py2.py3-none-any.whl (394 kB) | ||
| |████████████████████████████████| 394 kB 24.4 MB/s | ||
| Downloading cup-3.19.1-py2.py3-none-any.whl (394 kB) | ||
| |████████████████████████████████| 394 kB 21.3 MB/s | ||
| Downloading cup-3.19.0-py2.py3-none-any.whl (394 kB) | ||
| |████████████████████████████████| 394 kB 26.2 MB/s | ||
| Downloading cup-3.18.0-py2.py3-none-any.whl (393 kB) | ||
| |████████████████████████████████| 393 kB 22.1 MB/s | ||
| Downloading cup-3.17.0-py2.py3-none-any.whl (382 kB) | ||
| |████████████████████████████████| 382 kB 23.8 MB/s | ||
| Downloading cup-3.16.0-py2.py3-none-any.whl (376 kB) | ||
| |████████████████████████████████| 376 kB 27.5 MB/s | ||
| Downloading cup-3.15.1-py2.py3-none-any.whl (385 kB) | ||
| |████████████████████████████████| 385 kB 30.4 MB/s | ||
| INFO: pip is looking at multiple versions of this package to determine | ||
| which version is compatible with other requirements. | ||
| This could take a while. | ||
| Downloading cup-3.15.0-py2.py3-none-any.whl (378 kB) | ||
| |████████████████████████████████| 378 kB 21.4 MB/s | ||
| Downloading cup-3.14.0-py2.py3-none-any.whl (372 kB) | ||
| |████████████████████████████████| 372 kB 21.1 MB/s | ||
| ``` | ||
| These multiple `Downloading cup-{version}` lines show that pip is backtracking | ||
| choices it is making during dependency resolution. | ||
| ```` | ||
|
|
||
| If pip starts backtracking during dependency resolution, it does not know how | ||
| many choices it will reconsider, and how much computation would be needed. | ||
|
|
||
| For the user, this means it can take a long time to complete when pip starts | ||
| backtracking. In the case where a package has a lot of versions, arriving at a | ||
| good candidate can take a lot of time. The amount of time depends on the | ||
| package size, the number of versions pip must try, and various other factors. | ||
|
|
||
| Backtracking reduces the risk that installing a new package will accidentally | ||
| break an existing installed package, and so reduces the risk that your | ||
| environment gets messed up. To do this, pip has to do more work, to find out | ||
| which version of a package is a good candidate to install. |
| @@ -0,0 +1,19 @@ | ||
| # Topic Guides | ||
|
|
||
| These pages provide detailed information on individual topics. | ||
|
|
||
| ```{note} | ||
| This section of the documentation is currently being fleshed out. See | ||
| {issue}`9475` for more details. | ||
| ``` | ||
|
|
||
| ```{toctree} | ||
| :maxdepth: 1 | ||
| authentication | ||
| caching | ||
| configuration | ||
| dependency-resolution | ||
| repeatable-installs | ||
| vcs-support | ||
| ``` |
| @@ -0,0 +1,98 @@ | ||
| # Repeatable Installs | ||
|
|
||
| pip can be used to achieve various levels of repeatable environments. This page | ||
| walks through increasingly stricter definitions of what "repeatable" means. | ||
|
|
||
| ## Pinning the package versions | ||
|
|
||
| Pinning package versions of your dependencies in the requirements file | ||
| protects you from bugs or incompatibilities in newly released versions: | ||
|
|
||
| ``` | ||
| SomePackage == 1.2.3 | ||
| DependencyOfSomePackage == 4.5.6 | ||
| ``` | ||
|
|
||
| ```{note} | ||
| Pinning refers to using the `==` operator to require the package to be a | ||
| specific version. | ||
| ``` | ||
|
|
||
| A requirements file, containing pinned package versions can be generated using | ||
| {ref}`pip freeze`. This would not only the top-level packages, but also all of | ||
| their transitive dependencies. Performing the installation using | ||
| {ref}`--no-deps <install_--no-deps>` would provide an extra dose of insurance | ||
| against installing anything not explicitly listed. | ||
|
|
||
| This strategy is easy to implement and works across OSes and architectures. | ||
| However, it trusts the locations you're fetching the packages from (like PyPI) | ||
| and the certificate authority chain. It also relies on those locations not | ||
| allowing packages to change without a version increase. (PyPI does protect | ||
| against this.) | ||
|
|
||
| ## Hash-checking | ||
|
|
||
| Beyond pinning version numbers, you can add hashes against which to verify | ||
| downloaded packages: | ||
|
|
||
| ```none | ||
| FooProject == 1.2 --hash=sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 | ||
| ``` | ||
|
|
||
| This protects against a compromise of PyPI or the HTTPS certificate chain. It | ||
| also guards against a package changing without its version number changing (on | ||
| indexes that allow this). This approach is a good fit for automated server | ||
| deployments. | ||
|
|
||
| Hash-checking mode is a labour-saving alternative to running a private index | ||
| server containing approved packages: it removes the need to upload packages, | ||
| maintain ACLs, and keep an audit trail (which a VCS gives you on the | ||
| requirements file for free). It can also substitute for a vendored library, | ||
| providing easier upgrades and less VCS noise. It does not, of course, | ||
| provide the availability benefits of a private index or a vendored library. | ||
|
|
||
| [pip-tools] is a package that builds upon pip, and provides a good workflow for | ||
| managing and generating requirements files. | ||
|
|
||
| [pip-tools]: https://github.com/jazzband/pip-tools#readme | ||
|
|
||
| ## Using a wheelhouse (AKA Installation Bundles) | ||
|
|
||
| {ref}`pip wheel` can be used to generate and package all of a project's | ||
| dependencies, with all the compilation performed, into a single directory that | ||
| can be converted into a single archive. This archive then allows installation | ||
| when index servers are unavailable and avoids time-consuming recompilation. | ||
|
|
||
| ````{admonition} Example | ||
| Creating the bundle, on a modern Unix system: | ||
| ``` | ||
| $ tempdir=$(mktemp -d /tmp/wheelhouse-XXXXX) | ||
| $ python -m pip wheel -r requirements.txt --wheel-dir=$tempdir | ||
| $ cwd=`pwd` | ||
| $ (cd "$tempdir"; tar -cjvf "$cwd/bundled.tar.bz2" *) | ||
| ``` | ||
| Installing from the bundle, on a modern Unix system: | ||
| ``` | ||
| $ tempdir=$(mktemp -d /tmp/wheelhouse-XXXXX) | ||
| $ (cd $tempdir; tar -xvf /path/to/bundled.tar.bz2) | ||
| $ python -m pip install --force-reinstall --no-index --no-deps $tempdir/* | ||
| ``` | ||
| ```` | ||
|
|
||
| Note that such a wheelhouse contains compiled packages, which are typically | ||
| OS and architecture-specific, so these archives are not necessarily portable | ||
| across machines. | ||
|
|
||
| Hash-checking mode can also be used along with this method (since this uses a | ||
| requirements file as well), to ensure that future archives are built with | ||
| identical packages. | ||
|
|
||
| ```{warning} | ||
| Beware of the `setup_requires` keyword arg in {file}`setup.py`. The (rare) | ||
| packages that use it will cause those dependencies to be downloaded by | ||
| setuptools directly, skipping pip's protections. If you need to use such a | ||
| package, see {ref}`Controlling setup_requires <controlling-setup-requires>`. | ||
| ``` |
| @@ -0,0 +1,162 @@ | ||
| # VCS Support | ||
|
|
||
| pip supports installing from various version control systems (VCS). | ||
| This support requires a working executable to be available (for the version | ||
| control system being used). It is used through URL prefixes: | ||
|
|
||
| - Git -- `git+` | ||
| - Mercurial -- `hg+` | ||
| - Subversion -- `svn+` | ||
| - Bazaar -- `bzr+` | ||
|
|
||
| ## Supported VCS | ||
|
|
||
| ### Git | ||
|
|
||
| The supported schemes are `git+file`, `git+https`, `git+ssh`, `git+http`, | ||
| `git+git` and `git`. Here are some of the supported forms: | ||
|
|
||
| ```none | ||
| git+ssh://git.example.com/MyProject#egg=MyProject | ||
| git+file:///home/user/projects/MyProject#egg=MyProject | ||
| git+https://git.example.com/MyProject#egg=MyProject | ||
| ``` | ||
|
|
||
| ```{warning} | ||
| The use of `git`, `git+git`, and `git+http` schemes is discouraged. | ||
| The former two use [the Git Protocol], which lacks authentication, and HTTP is | ||
| insecure due to lack of TLS based encryption. | ||
| ``` | ||
|
|
||
| [the Git Protocol]: https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols | ||
|
|
||
| It is also possible to specify a "git ref" such as branch name, a commit hash or | ||
| a tag name: | ||
|
|
||
| ```none | ||
| git+https://git.example.com/MyProject.git@master#egg=MyProject | ||
| git+https://git.example.com/MyProject.git@v1.0#egg=MyProject | ||
| git+https://git.example.com/MyProject.git@da39a3ee5e6b4b0d3255bfef95601890afd80709#egg=MyProject | ||
| git+https://git.example.com/MyProject.git@refs/pull/123/head#egg=MyProject | ||
| ``` | ||
|
|
||
| When passing a commit hash, specifying a full hash is preferable to a partial | ||
| hash because a full hash allows pip to operate more efficiently (e.g. by | ||
| making fewer network calls). | ||
|
|
||
| ### Mercurial | ||
|
|
||
| The supported schemes are `hg+file`, `hg+http`, `hg+https`, `hg+ssh` | ||
| and `hg+static-http`. Here are some of the supported forms: | ||
|
|
||
| ``` | ||
| hg+http://hg.myproject.org/MyProject#egg=MyProject | ||
| hg+https://hg.myproject.org/MyProject#egg=MyProject | ||
| hg+ssh://hg.myproject.org/MyProject#egg=MyProject | ||
| hg+file:///home/user/projects/MyProject#egg=MyProject | ||
| ``` | ||
|
|
||
| It is also possible to specify a revision number, a revision hash, a tag name | ||
| or a local branch name: | ||
|
|
||
| ```none | ||
| hg+http://hg.example.com/MyProject@da39a3ee5e6b#egg=MyProject | ||
| hg+http://hg.example.com/MyProject@2019#egg=MyProject | ||
| hg+http://hg.example.com/MyProject@v1.0#egg=MyProject | ||
| hg+http://hg.example.com/MyProject@special_feature#egg=MyProject | ||
| ``` | ||
|
|
||
| ### Subversion | ||
|
|
||
| The supported schemes are `svn`, `svn+svn`, `svn+http`, `svn+https` and | ||
| `svn+ssh`. Here are some of the supported forms: | ||
|
|
||
| ```none | ||
| svn+https://svn.example.com/MyProject#egg=MyProject | ||
| svn+ssh://svn.example.com/MyProject#egg=MyProject | ||
| svn+ssh://user@svn.example.com/MyProject#egg=MyProject | ||
| ``` | ||
|
|
||
| You can also give specific revisions to an SVN URL, like so: | ||
|
|
||
| ```none | ||
| -e svn+http://svn.example.com/svn/MyProject/trunk@2019#egg=MyProject | ||
| -e svn+http://svn.example.com/svn/MyProject/trunk@{20080101}#egg=MyProject | ||
| ``` | ||
|
|
||
| Note that you need to use [Editable VCS installs](#editable-vcs-installs) for | ||
| using specific revisions from Subversion. | ||
|
|
||
| ### Bazaar | ||
|
|
||
| The supported schemes are `bzr+http`, `bzr+https`, `bzr+ssh`, `bzr+sftp`, | ||
| `bzr+ftp` and `bzr+lp`. Here are the supported forms: | ||
|
|
||
| ```none | ||
| bzr+http://bzr.example.com/MyProject/trunk#egg=MyProject | ||
| bzr+sftp://user@example.com/MyProject/trunk#egg=MyProject | ||
| bzr+ssh://user@example.com/MyProject/trunk#egg=MyProject | ||
| bzr+ftp://user@example.com/MyProject/trunk#egg=MyProject | ||
| bzr+lp:MyProject#egg=MyProject | ||
| ``` | ||
|
|
||
| Tags or revisions can be installed like so: | ||
|
|
||
| ```none | ||
| bzr+https://bzr.example.com/MyProject/trunk@2019#egg=MyProject | ||
| bzr+http://bzr.example.com/MyProject/trunk@v1.0#egg=MyProject | ||
| ``` | ||
|
|
||
| (editable-vcs-installs)= | ||
|
|
||
| ## Editable VCS installs | ||
|
|
||
| VCS projects can be installed in {ref}`editable mode <editable-installs>` (using | ||
| the {ref}`--editable <install_--editable>` option) or not. | ||
|
|
||
| - The default clone location (for editable installs) is: | ||
|
|
||
| - `<venv path>/src/SomeProject` in virtual environments | ||
| - `<cwd>/src/SomeProject` for global Python installs | ||
|
|
||
| The {ref}`--src <install_--src>` option can be used to modify this location. | ||
|
|
||
| - For non-editable installs, the project is built locally in a temp dir and then | ||
| installed normally. | ||
|
|
||
| Note that if a satisfactory version of the package is already installed, the | ||
| VCS source will not overwrite it without an `--upgrade` flag. Further, pip | ||
| looks at the package version, at the target revision to determine what action to | ||
| take on the VCS requirement (not the commit itself). | ||
|
|
||
| The {ref}`pip freeze` subcommand will record the VCS requirement specifier | ||
| (referencing a specific commit) only if the install is done with the editable | ||
| option. | ||
|
|
||
| ## URL fragments | ||
|
|
||
| pip looks at 2 fragments for VCS URLs: | ||
|
|
||
| - `egg`: For specifying the "project name" for use in pip's dependency | ||
| resolution logic. eg: `egg=project_name` | ||
| - `subdirectory`: For specifying the path to the Python package, when it is not | ||
| in the root of the VCS directory. eg: `pkg_dir` | ||
|
|
||
| ````{admonition} Example | ||
| If your repository layout is: | ||
| ``` | ||
| pkg_dir | ||
| ├── setup.py # setup.py for package "pkg" | ||
| └── some_module.py | ||
| other_dir | ||
| └── some_file | ||
| some_other_file | ||
| ``` | ||
| Then, to install from this repository, the syntax would be: | ||
| ```{pip-cli} | ||
| $ pip install -e "vcs+protocol://repo_url/#egg=pkg&subdirectory=pkg_dir" | ||
| ``` | ||
| ```` |