diff --git a/docs/html/cli/pip_install.rst b/docs/html/cli/pip_install.rst index 5747cc14a6d..cfff4f7e270 100644 --- a/docs/html/cli/pip_install.rst +++ b/docs/html/cli/pip_install.rst @@ -154,91 +154,15 @@ Requirements File Format This section has been moved to :doc:`../reference/requirements-file-format`. -.. _`Requirement Specifiers`: - Requirement Specifiers ---------------------- -pip supports installing from a package index using a :term:`requirement -specifier `. Generally speaking, a requirement -specifier is composed of a project name followed by optional :term:`version -specifiers `. :pep:`508` contains a full specification -of the format of a requirement. Since version 18.1 pip supports the -``url_req``-form specification. - -Some examples: - - :: - - SomeProject - SomeProject == 1.3 - SomeProject >=1.2,<2.0 - SomeProject[foo, bar] - SomeProject~=1.4.2 - -Since version 6.0, pip also supports specifiers containing `environment markers -`__ like so: - - :: - - SomeProject ==5.4 ; python_version < '3.8' - SomeProject; sys_platform == 'win32' - -Since version 19.3, pip also supports `direct references -`__ like so: - - :: - - SomeProject @ file:///somewhere/... - -Environment markers are supported in the command line and in requirements files. - -.. note:: - - Use quotes around specifiers in the shell when using ``>``, ``<``, or when - using environment markers. Don't use quotes in requirement files. [1]_ - - -.. _`Per-requirement Overrides`: +This section has been moved to :doc:`../reference/requirement-specifiers`. Per-requirement Overrides ------------------------- -Since version 7.0 pip supports controlling the command line options given to -``setup.py`` via requirements files. - -.. warning:: - - This disables the use of wheels (cached or otherwise). - -The ``--global-option`` and ``--install-option`` options are used to pass -options to ``setup.py``. For example: - - :: - - FooProject >= 1.2 --global-option="--no-user-cfg" \ - --install-option="--prefix='/usr/local'" \ - --install-option="--no-compile" - -The above translates roughly into running FooProject's ``setup.py`` -script as: - - :: - - python setup.py --no-user-cfg install --prefix='/usr/local' --no-compile - -Note that the only way of giving more than one option to ``setup.py`` -is through multiple ``--global-option`` and ``--install-option`` -options, as shown in the example above. The value of each option is -passed as a single argument to the ``setup.py`` script. Therefore, a -line such as the following is invalid and would result in an -installation error. - -:: - - # Invalid. Please use '--install-option' twice as shown above. - FooProject >= 1.2 --install-option="--prefix=/usr/local --no-compile" - +This is now covered in :doc:`../reference/requirements-file-format`. .. _`Pre Release Versions`: @@ -315,232 +239,20 @@ Wheel Cache This is now covered in :doc:`../topics/caching`. -.. _`hash-checking mode`: - -Hash-Checking Mode +Hash checking mode ------------------ -Since version 8.0, pip can check downloaded package archives against local -hashes to protect against remote tampering. To verify a package against one or -more hashes, add them to the end of the line:: - - FooProject == 1.2 --hash=sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 \ - --hash=sha256:486ea46224d1bb4fb680f34f7c9ad96a8f24ec88be73ea8e5a6c65260e9cb8a7 - -(The ability to use multiple hashes is important when a package has both -binary and source distributions or when it offers binary distributions for a -variety of platforms.) - -The recommended hash algorithm at the moment is sha256, but stronger ones are -allowed, including all those supported by ``hashlib``. However, weaker ones -such as md5, sha1, and sha224 are excluded to avoid giving a false sense of -security. - -Hash verification is an all-or-nothing proposition. Specifying a ``--hash`` -against any requirement not only checks that hash but also activates a global -*hash-checking mode*, which imposes several other security restrictions: - -* Hashes are required for all requirements. This is because a partially-hashed - requirements file is of little use and thus likely an error: a malicious - actor could slip bad code into the installation via one of the unhashed - requirements. Note that hashes embedded in URL-style requirements via the - ``#md5=...`` syntax suffice to satisfy this rule (regardless of hash - strength, for legacy reasons), though you should use a stronger - hash like sha256 whenever possible. -* Hashes are required for all dependencies. An error results if there is a - dependency that is not spelled out and hashed in the requirements file. -* Requirements that take the form of project names (rather than URLs or local - filesystem paths) must be pinned to a specific version using ``==``. This - prevents a surprising hash mismatch upon the release of a new version - that matches the requirement specifier. -* ``--egg`` is disallowed, because it delegates installation of dependencies - to setuptools, giving up pip's ability to enforce any of the above. - -.. _`--require-hashes`: - -Hash-checking mode can be forced on with the ``--require-hashes`` command-line -option: - -.. tab:: Unix/macOS - - .. code-block:: console - - $ python -m pip install --require-hashes -r requirements.txt - ... - Hashes are required in --require-hashes mode (implicitly on when a hash is - specified for any package). These requirements were missing hashes, - leaving them open to tampering. These are the hashes the downloaded - archives actually had. You can add lines like these to your requirements - files to prevent tampering. - pyelasticsearch==1.0 --hash=sha256:44ddfb1225054d7d6b1d02e9338e7d4809be94edbe9929a2ec0807d38df993fa - more-itertools==2.2 --hash=sha256:93e62e05c7ad3da1a233def6731e8285156701e3419a5fe279017c429ec67ce0 - -.. tab:: Windows - - .. code-block:: console - - C:\> py -m pip install --require-hashes -r requirements.txt - ... - Hashes are required in --require-hashes mode (implicitly on when a hash is - specified for any package). These requirements were missing hashes, - leaving them open to tampering. These are the hashes the downloaded - archives actually had. You can add lines like these to your requirements - files to prevent tampering. - pyelasticsearch==1.0 --hash=sha256:44ddfb1225054d7d6b1d02e9338e7d4809be94edbe9929a2ec0807d38df993fa - more-itertools==2.2 --hash=sha256:93e62e05c7ad3da1a233def6731e8285156701e3419a5fe279017c429ec67ce0 - - -This can be useful in deploy scripts, to ensure that the author of the -requirements file provided hashes. It is also a convenient way to bootstrap -your list of hashes, since it shows the hashes of the packages it fetched. It -fetches only the preferred archive for each package, so you may still need to -add hashes for alternatives archives using :ref:`pip hash`: for instance if -there is both a binary and a source distribution. - -The :ref:`wheel cache ` is disabled in hash-checking mode to -prevent spurious hash mismatch errors. These would otherwise occur while -installing sdists that had already been automatically built into cached wheels: -those wheels would be selected for installation, but their hashes would not -match the sdist ones from the requirements file. A further complication is that -locally built wheels are nondeterministic: contemporary modification times make -their way into the archive, making hashes unpredictable across machines and -cache flushes. Compilation of C code adds further nondeterminism, as many -compilers include random-seeded values in their output. However, wheels fetched -from index servers are the same every time. They land in pip's HTTP cache, not -its wheel cache, and are used normally in hash-checking mode. The only downside -of having the wheel cache disabled is thus extra build time for sdists, and -this can be solved by making sure pre-built wheels are available from the index -server. - -Hash-checking mode also works with :ref:`pip download` and :ref:`pip wheel`. -See :doc:`../topics/repeatable-installs` for a comparison of hash-checking mode -with other repeatability strategies. - -.. 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 hash-checking. If you need to use - such a package, see :ref:`Controlling - setup_requires `. - -.. warning:: - - Be careful not to nullify all your security work when you install your - actual project by using setuptools directly: for example, by calling - ``python setup.py install``, ``python setup.py develop``, or - ``easy_install``. Setuptools will happily go out and download, unchecked, - anything you missed in your requirements file—and it’s easy to miss things - as your project evolves. To be safe, install your project using pip and - :ref:`--no-deps `. - - Instead of ``python setup.py develop``, use... - - .. tab:: Unix/macOS - - .. code-block:: shell - - python -m pip install --no-deps -e . +This is now covered in :doc:`../topics/secure-installs`. - .. tab:: Windows - - .. code-block:: shell - - py -m pip install --no-deps -e . - - - Instead of ``python setup.py install``, use... - - .. tab:: Unix/macOS - - .. code-block:: shell - - python -m pip install --no-deps . - - .. tab:: Windows - - .. code-block:: shell - - py -m pip install --no-deps . - -Hashes from PyPI -^^^^^^^^^^^^^^^^ - -PyPI provides an MD5 hash in the fragment portion of each package download URL, -like ``#md5=123...``, which pip checks as a protection against download -corruption. Other hash algorithms that have guaranteed support from ``hashlib`` -are also supported here: sha1, sha224, sha384, sha256, and sha512. Since this -hash originates remotely, it is not a useful guard against tampering and thus -does not satisfy the ``--require-hashes`` demand that every package have a -local hash. - - -Local project installs +Local Project Installs ---------------------- -pip supports installing local project in both regular mode and editable mode. -You can install local projects by specifying the project path to pip: - -.. tab:: Unix/macOS - - .. code-block:: shell - - python -m pip install path/to/SomeProject - -.. tab:: Windows - - .. code-block:: shell +This is now covered in :doc:`../topics/local-project-installs`. - py -m pip install path/to/SomeProject - -.. note:: - - Depending on the build backend used by the project, this may generate - secondary build artifacts in the project directory, such as the - ``.egg-info`` and ``build`` directories in the case of the setuptools - backend. - - Pip has a legacy behaviour that copies the entire project directory to a - temporary location and installs from there. This approach was the cause of - several performance and correctness issues, so it is now disabled by - default, and it is planned that pip 22.1 will remove it. - - To opt in to the legacy behavior, specify the - ``--use-deprecated=out-of-tree-build`` option in pip's command line. - - -.. _`editable-installs`: - -"Editable" Installs -^^^^^^^^^^^^^^^^^^^ - -"Editable" installs are fundamentally `"setuptools develop mode" -`_ -installs. - -You can install local projects or VCS projects in "editable" mode: - -.. tab:: Unix/macOS - - .. code-block:: shell - - python -m pip install -e path/to/SomeProject - python -m pip install -e git+http://repo/my_project.git#egg=SomeProject - -.. tab:: Windows - - .. code-block:: shell - - py -m pip install -e path/to/SomeProject - py -m pip install -e git+http://repo/my_project.git#egg=SomeProject - - -(See the :doc:`../topics/vcs-support` section above for more information on VCS-related syntax.) - -For local projects, the "SomeProject.egg-info" directory is created relative to -the project path. This is one advantage over just using ``setup.py develop``, -which creates the "egg-info" directly relative the current working directory. +Editable installs +----------------- +This is now covered in :doc:`../topics/local-project-installs`. Build System Interface ---------------------- @@ -834,10 +546,5 @@ Examples py -m pip install SomePackage1 SomePackage2 --no-binary SomePackage1 ----- - -.. [1] This is true with the exception that pip v7.0 and v7.0.1 required quotes - around specifiers containing environment markers in requirement files. - .. _extras: https://www.python.org/dev/peps/pep-0508/#extras .. _PyPI: https://pypi.org/ diff --git a/docs/html/reference/index.md b/docs/html/reference/index.md index 8d690188d7a..855dc79b37a 100644 --- a/docs/html/reference/index.md +++ b/docs/html/reference/index.md @@ -7,5 +7,6 @@ interoperability standards that pip utilises/implements. :titlesonly: build-system/index +requirement-specifiers requirements-file-format ``` diff --git a/docs/html/reference/requirement-specifiers.md b/docs/html/reference/requirement-specifiers.md new file mode 100644 index 00000000000..d1449e5ef3a --- /dev/null +++ b/docs/html/reference/requirement-specifiers.md @@ -0,0 +1,61 @@ +(Requirement Specifiers)= + +# Requirement Specifiers + +pip supports installing from a package index using a {term}`requirement specifier `. Generally speaking, a requirement specifier is composed of a project name followed by optional {term}`version specifiers `. + +{pep}`508` contains a full specification of the format of a requirement. + +```{versionadded} 6.0 +Support for environment markers. +``` + +```{versionadded} 19.1 +Support for the direct URL reference form. +``` + +## Overview + +A requirement specifier comes in two forms: + +- name-based, which is composed of: + + - a package name (eg: `requests`) + - optionally, a set of "extras" that serve to install optional dependencies (eg: `security`) + - optionally, constraints to apply on the version of the package + - optionally, environment markers + +- URL-based, which is composed of: + + - a package name (eg: `requests`) + - optionally, a set of "extras" that serve to install optional dependencies (eg: `security`) + - a URL for the package + - optionally, environment markers + +## Examples + +A few example name-based requirement specifiers: + +``` +SomeProject +SomeProject == 1.3 +SomeProject >= 1.2, < 2.0 +SomeProject[foo, bar] +SomeProject ~= 1.4.2 +SomeProject == 5.4 ; python_version < '3.8' +SomeProject ; sys_platform == 'win32' +requests [security] >= 2.8.1, == 2.8.* ; python_version < "2.7" +``` + +```{note} +Use quotes around specifiers in the shell when using `>`, `<`, or when using environment markers. + +Do _not_ use quotes in requirement files. There is only one exception: pip v7.0 and v7.0.1 (from May 2015) required quotes around specifiers containing environment markers in requirement files. +``` + +A few example URL-based requirement specifiers: + +```none +pip @ https://github.com/pypa/pip/archive/22.0.2.zip +requests [security] @ https://github.com/psf/requests/archive/refs/heads/main.zip ; python_version >= "3.11" +``` diff --git a/docs/html/reference/requirements-file-format.md b/docs/html/reference/requirements-file-format.md index d05f1acca10..cf1d434eb6a 100644 --- a/docs/html/reference/requirements-file-format.md +++ b/docs/html/reference/requirements-file-format.md @@ -15,13 +15,38 @@ consumption by pip, and other tools should take that into account before using it for their own purposes. ``` +## Example + +``` +# This is a comment, to show how #-prefixed lines are ignored. +# It is possible to specify requirements as plain names. +pytest +pytest-cov +beautifulsoup4 + +# The syntax supported here is the same as that of requirement specifiers. +docopt == 0.6.1 +requests [security] >= 2.8.1, == 2.8.* ; python_version < "2.7" +urllib3 @ https://github.com/urllib3/urllib3/archive/refs/tags/1.26.8.zip + +# It is possible to refer to other requirement files or constraints files. +-r other-requirements.txt +-c constraints.txt + +# It is possible to refer to specific local distribution paths. +./downloads/numpy-1.9.2-cp34-none-win32.whl + +# It is possible to refer to URLs. +http://wxpython.org/Phoenix/snapshot-builds/wxPython_Phoenix-3.0.3.dev1820+49a8884-cp34-none-win_amd64.whl +``` + ## Structure Each line of the requirements file indicates something to be installed, or arguments to {ref}`pip install`. The following forms are supported: - `[[--option]...]` -- ` [; markers] [[--option]...]` +- `` - `` - `[-e] ` - `[-e] ` @@ -74,13 +99,21 @@ and two {ref}`--find-links ` locations: ``` ```` +(per-requirement-options)= + ### Per-requirement options +```{versionadded} 7.0 + +``` + The options which can be applied to individual requirements are: - {ref}`--install-option ` - {ref}`--global-option ` -- `--hash` (for {ref}`Hash-Checking mode`) +- `--hash` (for {ref}`Hash-checking mode`) + +## Referring to other requirements files If you wish, you can refer to other requirements files, like this: @@ -118,30 +151,34 @@ and only specify the variable name for your requirements, letting pip lookup the value at runtime. This approach aligns with the commonly used [12-factor configuration pattern](https://12factor.net/config). -## Example -``` -###### Requirements without Version Specifiers ###### -pytest -pytest-cov -beautifulsoup4 +## Influencing the build system -###### Requirements with Version Specifiers ###### -# See https://www.python.org/dev/peps/pep-0440/#version-specifiers -docopt == 0.6.1 # Version Matching. Must be version 0.6.1 -keyring >= 4.1.1 # Minimum version 4.1.1 -coverage != 3.5 # Version Exclusion. Anything except version 3.5 -Mopidy-Dirble ~= 1.1 # Compatible release. Same as >= 1.1, == 1.* +```{danger} +This disables the use of wheels (cached or otherwise). This could mean that builds will be slower, less deterministic, less reliable and may not behave correctly upon installation. -###### Refer to other requirements files ###### --r other-requirements.txt +This mechanism is only preserved for backwards compatibility and should be considered deprecated. A future release of pip may drop these options. +``` -###### A particular file ###### -./downloads/numpy-1.9.2-cp34-none-win32.whl -http://wxpython.org/Phoenix/snapshot-builds/wxPython_Phoenix-3.0.3.dev1820+49a8884-cp34-none-win_amd64.whl +The `--global-option` and `--install-option` options are used to pass options to `setup.py`. + +```{attention} +These options are highly coupled with how pip invokes setuptools using the {doc}`../reference/build-system/setup-py` build system interface. It is not compatible with newer {doc}`../reference/build-system/pyproject-toml` build system interface. -###### Additional Requirements without Version Specifiers ###### -# Same as 1st section, just here to show that you can put things in any order. -rejected -green +This is will not work with other build-backends or newer setup.cfg-only projects. ``` + +If you have a declaration like: + + FooProject >= 1.2 --global-option="--no-user-cfg" \ + --install-option="--prefix='/usr/local'" \ + --install-option="--no-compile" + +The above translates roughly into running FooProject's `setup.py` script as: + + python setup.py --no-user-cfg install --prefix='/usr/local' --no-compile + +Note that the only way of giving more than one option to `setup.py` is through multiple `--global-option` and `--install-option` options, as shown in the example above. The value of each option is passed as a single argument to the `setup.py` script. Therefore, a line such as the following is invalid and would result in an installation error. + + # Invalid. Please use '--install-option' twice as shown above. + FooProject >= 1.2 --install-option="--prefix=/usr/local --no-compile" diff --git a/docs/html/topics/index.md b/docs/html/topics/index.md index 10eb5dddaee..011205a111d 100644 --- a/docs/html/topics/index.md +++ b/docs/html/topics/index.md @@ -14,6 +14,8 @@ authentication caching configuration dependency-resolution +local-project-installs repeatable-installs +secure-installs vcs-support ``` diff --git a/docs/html/topics/local-project-installs.md b/docs/html/topics/local-project-installs.md new file mode 100644 index 00000000000..331afadb8c3 --- /dev/null +++ b/docs/html/topics/local-project-installs.md @@ -0,0 +1,65 @@ +# Local project installs + +It is extremely common to have a project, available in a folder/directory on your computer [^1] that you wish to install. + +With pip, depending on your usecase, there are two ways to do this: + +- A regular install +- An editable install + +## Regular installs + +You can install local projects by specifying the project path to pip: + +```{pip-cli} +$ pip install path/to/SomeProject +``` + +This will install the project into the Python that pip is associated with, in a manner similar to how it would actually be installed. + +This is what should be used in CI system and for deployments, since it most closely mirrors how a package would get installed if you build a distribution and installed from it (because that's _exactly_ what it does). + +(editable-installs)= + +## Editable installs + +You can install local projects in "editable" mode: + +```{pip-cli} +$ pip install -e path/to/SomeProject +``` + +Editable installs allow you to install your project without copying any files. Instead, the files in the development directory are added to Python's import path. This approach is well suited for development and is also known as a "development installation". + +With an editable install, you only need to perform a re-installation if you change the project metadata (eg: version, what scripts need to be generated etc). You will still need to run build commands when you need to perform a compilation for non-Python code in the project (eg: C extensions). + +```{caution} +It is possible to see behaviour differences between regular installs vs editable installs. In case you distribute the project as a "distribution package", users will see the behaviour of regular installs -- thus, it is important to ensure that regular installs work correctly. +``` + +```{note} +This is functionally the same as [setuptools' develop mode], and that's precisely the mechanism used for setuptools-based projects. + +There are two advantages over using `setup.py develop` directly: + +- This works with non-setuptools build-backends as well. +- The ".egg-info" directory is created relative to the project path, when using pip. This is generally a better location than setuptools, which dumps it in the current working directory. +``` + +[setuptools' develop mode]: https://setuptools.readthedocs.io/en/latest/userguide/development_mode.html + +## Build artifacts + +```{versionchanged} 21.3 +The project being installed is no longer copied to a temporary directory before invoking the build system. +``` + +This behaviour change has several consequences: + +- Local project builds will now be significantly faster, for certain kinds of projects and on systems with slow I/O (eg: via network attached storage or overly aggressive antivirus software). +- Certain build backends (eg: `setuptools`) will litter the project directory with secondary build artifacts (eg: `.egg-info` directories). +- Certain build backends (eg: `setuptools`) may not be able to perform with parallel builds anymore, since they previously relied on the fact that pip invoked them in a separate directory for each build. + +A `--use-deprecated=out-of-tree-build` option is available, until pip 22.1, as a mechanism to aid users with transitioning to the newer model of in-tree-builds. + +[^1]: Specifically, the current machine's filesystem. diff --git a/docs/html/topics/secure-installs.md b/docs/html/topics/secure-installs.md new file mode 100644 index 00000000000..f012842b2ac --- /dev/null +++ b/docs/html/topics/secure-installs.md @@ -0,0 +1,100 @@ +# Secure installs + +By default, pip does not perform any checks to protect against remote tampering and involves running arbitrary code from distributions. It is, however, possible to use pip in a manner that changes these behaviours, to provide a more secure installation mechanism. + +This can be achieved by doing the following: + +- Enable {ref}`Hash-checking mode`, by passing {any}`--require-hashes` +- Disallow source distributions, by passing {any}`--only-binary :all: <--only-binary>` + +(Hash-checking mode)= + +## Hash-checking Mode + +```{versionadded} 8.0 + +``` + +This mode uses local hashes, embedded in a requirements.txt file, to protect against remote tampering and network issues. These hashes are specified using a `--hash` [per requirement option](per-requirement-options). + +Note that hash-checking is an all-or-nothing proposition. Specifying `--hash` against _any_ requirement will activate this mode globally. + +To add hashes for a package, add them to line as follows: + +``` +FooProject == 1.2 \ + --hash=sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 \ + --hash=sha256:486ea46224d1bb4fb680f34f7c9ad96a8f24ec88be73ea8e5a6c65260e9cb8a7 +``` + +### Additional restrictions + +- Hashes are required for _all_ requirements. + + This is because a partially-hashed requirements file is of little use and thus likely an error: a malicious actor could slip bad code into the installation via one of the unhashed requirements. + + Note that hashes embedded in URL-style requirements via the `#md5=...` syntax suffice to satisfy this rule (regardless of hash strength, for legacy reasons), though you should use a stronger hash like sha256 whenever possible. + +- Hashes are required for _all_ dependencies. + + If there is a dependency that is not spelled out and hashed in the requirements file, it will result in an error. + +- Requirements must be pinned (either to a URL, filesystem path or using `==`). + + This prevents a surprising hash mismatch upon the release of a new version that matches the requirement specifier. + +### Forcing Hash-checking mode + +It is possible to force the hash checking mode to be enabled, by passing `--require-hashes` command-line option. + +This can be useful in deploy scripts, to ensure that the author of the requirements file provided hashes. It is also a convenient way to bootstrap your list of hashes, since it shows the hashes of the packages it fetched. It fetches only the preferred archive for each package, so you may still need to add hashes for alternatives archives using {ref}`pip hash`: for instance if there is both a binary and a source distribution. + +### Hash algorithms + +The recommended hash algorithm at the moment is sha256, but stronger ones are allowed, including all those supported by `hashlib`. However, weaker ones such as md5, sha1, and sha224 are excluded to avoid giving a false sense of security. + +### Multiple hashes per package + +It is possible to use multiple hashes for each package. This is important when a package offers binary distributions for a variety of platforms or when it is important to allow both binary and source distributions. + +### Interaction with caching + +The {ref}`locally-built wheel cache ` is disabled in hash-checking mode to prevent spurious hash mismatch errors. + +These would otherwise occur while installing sdists that had already been automatically built into cached wheels: those wheels would be selected for installation, but their hashes would not match the sdist ones from the requirements file. + +A further complication is that locally built wheels are nondeterministic: contemporary modification times make their way into the archive, making hashes unpredictable across machines and cache flushes. Compilation of C code adds further nondeterminism, as many compilers include random-seeded values in their output. + +However, wheels fetched from index servers are required to be the same every time. They land in pip's HTTP cache, not its wheel cache, and are used normally in hash-checking mode. The only downside of having the wheel cache disabled is thus extra build time for sdists, and this can be solved by making sure pre-built wheels are available from the index server. + +### Using hashes from PyPI (or other index servers) + +PyPI (and certain other index servers) provides a hash for the distribution, in the fragment portion of each download URL, like `#sha256=123...`, which pip checks as a protection against download corruption. + +Other hash algorithms that have guaranteed support from `hashlib` are also supported here: sha1, sha224, sha384, sha256, and sha512. Since this hash originates remotely, it is not a useful guard against tampering and thus does not satisfy the `--require-hashes` demand that every package have a local hash. + +## Repeatable installs + +Hash-checking mode also works with {ref}`pip download` and {ref}`pip wheel`. See {doc}`../topics/repeatable-installs` for a comparison of hash-checking mode with other repeatability strategies. + +```{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 hash-checking. If you need to use such a package, see {ref}`controlling setup_requires `. +``` + +## Do not use setuptools directly + +Be careful not to nullify all your security work by installing your actual project by using setuptools' deprecated interfaces directly: for example, by calling `python setup.py install`, `python setup.py develop`, or `easy_install`. + +These will happily go out and download, unchecked, anything you missed in your requirements file and it’s easy to miss things as your project evolves. To be safe, install your project using pip and {any}`--no-deps`. + +Instead of `python setup.py install`, use: + +```{pip-cli} +$ pip install --no-deps . +``` + +Instead of `python setup.py develop`, use: + +```{pip-cli} +$ pip install --no-deps -e . +``` diff --git a/news/10899.doc.rst b/news/10899.doc.rst new file mode 100644 index 00000000000..7e4f8872e28 --- /dev/null +++ b/news/10899.doc.rst @@ -0,0 +1 @@ +Add more dedicated topic and reference pages to the documentation.