From dc32c9357e775cd30a1a29a9e884dfee9b628205 Mon Sep 17 00:00:00 2001 From: Mennaalazaz <162923696+Mennaalazaz@users.noreply.github.com> Date: Thu, 11 Dec 2025 13:23:34 +0200 Subject: [PATCH 1/3] Add beginner example in Running pip section --- docs/html/user_guide.rst | 388 +++++++++++++++++++++------------------ news/13690.doc.rst | 2 + 2 files changed, 208 insertions(+), 182 deletions(-) create mode 100644 news/13690.doc.rst diff --git a/docs/html/user_guide.rst b/docs/html/user_guide.rst index 8711f0f9126..1ad7ff079cd 100644 --- a/docs/html/user_guide.rst +++ b/docs/html/user_guide.rst @@ -8,14 +8,14 @@ User Guide to consider if this content can live on its own, within a topic guide or a reference page. - There is active effort being put toward *reducing* the amount of content on + There is active effort being put toward reducing the amount of content on this specific page (https://github.com/pypa/pip/issues/9475) and moving it into more focused single-page documents that cover that specific topic. Running pip =========== -pip is a command line program. When you install pip, a ``pip`` command is added +pip is a command line program. When you install pip, a `pip` command is added to your system, which can be run from the command prompt as follows: .. tab:: Unix/macOS @@ -24,9 +24,9 @@ to your system, which can be run from the command prompt as follows: python -m pip - ``python -m pip`` executes pip using the Python interpreter you - specified as python. So ``/usr/bin/python3.7 -m pip`` means - you are executing pip for your interpreter located at ``/usr/bin/python3.7``. + `python -m pip` executes pip using the Python interpreter you + specified as python. So `/usr/bin/python3.7 -m pip` means + you are executing pip for your interpreter located at `/usr/bin/python3.7`. .. tab:: Windows @@ -34,9 +34,33 @@ to your system, which can be run from the command prompt as follows: py -m pip - ``py -m pip`` executes pip using the latest Python interpreter you + `py -m pip` executes pip using the latest Python interpreter you have installed. For more details, read the `Python Windows launcher`_ docs. +.. note:: + + *Quick example for beginners* + + To install a real package using pip, try the following example: + + .. tab:: Unix/macOS + + .. code-block:: shell + + python -m pip install requests + + This installs the popular `requests` library using the Python + interpreter currently in use. + + .. tab:: Windows + + .. code-block:: shell + + py -m pip install requests + + This installs the `requests` library using the latest Python + interpreter available on your system. + Installing Packages =================== @@ -64,24 +88,24 @@ Specifiers` py -m pip install SomePackage==1.0.4 # specific version py -m pip install 'SomePackage>=1.0.4' # minimum version -For more information and examples, see the :ref:`pip install` reference. +For more information and examples, see the :ref:pip install reference. .. _PyPI: https://pypi.org/ .. _`0-basic-authentication-credentials`: .. rubric:: Basic Authentication Credentials -This is now covered in :doc:`topics/authentication`. +This is now covered in :doc:topics/authentication. .. _`0-netrc-support`: .. rubric:: netrc Support -This is now covered in :doc:`topics/authentication`. +This is now covered in :doc:topics/authentication. .. _`0-keyring-support`: .. rubric:: Keyring Support -This is now covered in :doc:`topics/authentication`. +This is now covered in :doc:topics/authentication. Using a Proxy Server ==================== @@ -91,12 +115,12 @@ in many corporate environments requires an outbound HTTP proxy server. pip can be configured to connect through a proxy server in various ways: -* using the ``--proxy`` command-line option to specify a proxy in the form - ``scheme://[user:passwd@]proxy.server:port`` -* using ``proxy`` in a :ref:`config-file` -* by setting the standard environment-variables ``http_proxy``, ``https_proxy`` - and ``no_proxy``. -* using the environment variable ``PIP_USER_AGENT_USER_DATA`` to include +* using the `--proxy` command-line option to specify a proxy in the form + `scheme://[user:passwd@]proxy.server:port` +* using `proxy` in a :ref:config-file +* by setting the standard environment-variables `http_proxy`, `https_proxy` + and `no_proxy`. +* using the environment variable `PIP_USER_AGENT_USER_DATA` to include a JSON-encoded string in the user-agent variable used in pip's requests. @@ -107,7 +131,7 @@ Requirements Files ================== "Requirements files" are files containing a list of items to be -installed using :ref:`pip install` like so: +installed using :ref:pip install like so: .. tab:: Unix/macOS @@ -121,9 +145,9 @@ installed using :ref:`pip install` like so: py -m pip install -r requirements.txt -Details on the format of the files are here: :ref:`requirements-file-format`. +Details on the format of the files are here: :ref:requirements-file-format. -Logically, a Requirements file is just a list of :ref:`pip install` arguments +Logically, a Requirements file is just a list of :ref:pip install arguments placed in a file. Note that you should not rely on the items in the file being installed by pip in any particular order. @@ -133,10 +157,10 @@ be stored and served in a centralized place. In practice, there are 4 common uses of Requirements files: -1. Requirements files are used to hold the result from :ref:`pip freeze` for the - purpose of achieving :doc:`topics/repeatable-installs`. In +1. Requirements files are used to hold the result from :ref:pip freeze for the + purpose of achieving :doc:topics/repeatable-installs. In this case, your requirement file contains a pinned version of everything that - was installed when ``pip freeze`` was run. + was installed when `pip freeze` was run. .. tab:: Unix/macOS @@ -155,11 +179,11 @@ In practice, there are 4 common uses of Requirements files: 2. Requirements files are used to force pip to properly resolve dependencies. pip 20.2 and earlier `doesn't have true dependency resolution `_, but instead simply uses the first - specification it finds for a project. E.g. if ``pkg1`` requires - ``pkg3>=1.0`` and ``pkg2`` requires ``pkg3>=1.0,<=2.0``, and if ``pkg1`` is - resolved first, pip will only use ``pkg3>=1.0``, and could easily end up - installing a version of ``pkg3`` that conflicts with the needs of ``pkg2``. - To solve this problem, you can place ``pkg3>=1.0,<=2.0`` (i.e. the correct + specification it finds for a project. E.g. if `pkg1` requires + `pkg3>=1.0` and `pkg2` requires `pkg3>=1.0,<=2.0`, and if `pkg1` is + resolved first, pip will only use `pkg3>=1.0`, and could easily end up + installing a version of `pkg3` that conflicts with the needs of `pkg2`. + To solve this problem, you can place `pkg3>=1.0,<=2.0` (i.e. the correct specification) into your requirements file directly along with the other top level requirements. Like so:: @@ -168,8 +192,8 @@ In practice, there are 4 common uses of Requirements files: pkg3>=1.0,<=2.0 3. Requirements files are used to force pip to install an alternate version of a - sub-dependency. For example, suppose ``ProjectA`` in your requirements file - requires ``ProjectB``, but the latest version (v1.3) has a bug, you can force + sub-dependency. For example, suppose `ProjectA` in your requirements file + requires `ProjectB`, but the latest version (v1.3) has a bug, you can force pip to accept earlier versions like so:: ProjectA @@ -177,27 +201,27 @@ In practice, there are 4 common uses of Requirements files: 4. Requirements files are used to override a dependency with a local patch that lives in version control. For example, suppose a dependency - ``SomeDependency`` from PyPI has a bug, and you can't wait for an upstream + `SomeDependency` from PyPI has a bug, and you can't wait for an upstream fix. You could clone/copy the src, make the fix, and place it in VCS with the tag - ``sometag``. You'd reference it in your requirements file with a line like + `sometag`. You'd reference it in your requirements file with a line like so:: SomeDependency @ git+https://myvcs.com/some_dependency@sometag - If ``SomeDependency`` was previously a top-level requirement in your - requirements file, then **replace** that line with the new line. If - ``SomeDependency`` is a sub-dependency, then **add** the new line. + If `SomeDependency` was previously a top-level requirement in your + requirements file, then *replace* that line with the new line. If + `SomeDependency` is a sub-dependency, then *add* the new line. It's important to be clear that pip determines package dependencies using -the project metadata (typically in ``pyproject.toml`` or ``setup.py``), -not by discovering ``requirements.txt`` files embedded in projects. +the project metadata (typically in `pyproject.toml` or `setup.py`), +not by discovering `requirements.txt` files embedded in projects. See also: -* :ref:`requirements-file-format` -* :ref:`pip freeze` +* :ref:requirements-file-format +* :ref:pip freeze * `"setup.py vs requirements.txt" (an article by Donald Stufft) `_ @@ -210,7 +234,7 @@ Constraints Files Constraints files are requirements files that only control which version of a requirement is installed, not whether it is installed or not. Their syntax and -contents is a subset of :ref:`Requirements Files`, with several kinds of syntax +contents is a subset of :ref:Requirements Files, with several kinds of syntax not allowed: constraints must have a name, they cannot be editable, and they cannot specify extras. In terms of semantics, there is one key difference: Including a package in a constraints file does not trigger installation of the @@ -270,7 +294,7 @@ constraints only influence the versions of packages available during the build process. This is useful when you need to constrain build dependencies -(such as ``setuptools``, ``cython``, etc.) without affecting the +(such as `setuptools`, `cython`, etc.) without affecting the final installed environment. Use build constraints like so: @@ -287,7 +311,7 @@ Use build constraints like so: py -m pip install --build-constraint build-constraints.txt SomePackage -Example build constraints file (``build-constraints.txt``): +Example build constraints file (`build-constraints.txt`): .. code-block:: text @@ -304,11 +328,11 @@ Dependency Groups ================= "Dependency Groups" are lists of items to be installed stored in a -``pyproject.toml`` file. +`pyproject.toml` file. A dependency group is logically just a list of requirements, similar to the -contents of :ref:`Requirements Files`. Unlike requirements files, dependency -groups cannot contain non-package arguments for :ref:`pip install`. +contents of :ref:Requirements Files. Unlike requirements files, dependency +groups cannot contain non-package arguments for :ref:pip install. Groups can be declared like so: @@ -321,7 +345,7 @@ Groups can be declared like so: "pkg2", ] -and installed with :ref:`pip install` like so: +and installed with :ref:pip install like so: .. tab:: Unix/macOS @@ -335,20 +359,20 @@ and installed with :ref:`pip install` like so: py -m pip install --group groupA -Full details on the contents of ``[dependency-groups]`` and more examples are -available in :ref:`the specification documentation `. +Full details on the contents of `[dependency-groups]` and more examples are +available in :ref:the specification documentation . .. note:: Dependency Groups are defined by a standard, and therefore do not support - ``pip``-specific syntax for requirements, only :ref:`standard dependency + `pip`-specific syntax for requirements, only :ref:`standard dependency specifiers `. -``pip`` does not search projects or directories to discover ``pyproject.toml`` -files. The ``--group`` option is used to pass the path to the file, +`pip` does not search projects or directories to discover `pyproject.toml` +files. The `--group` option is used to pass the path to the file, and if the path is omitted, as in the example above, it defaults to -``pyproject.toml`` in the current directory. Using explicit paths, -:ref:`pip install` can use a file from another directory. For example: +`pyproject.toml` in the current directory. Using explicit paths, +:ref:pip install can use a file from another directory. For example: .. tab:: Unix/macOS @@ -372,7 +396,7 @@ at once. For example, with a directory structure like so:: + sub2/ - pyproject.toml -it is possible to install, from the ``project/`` directory, groups from the +it is possible to install, from the `project/` directory, groups from the subprojects thusly: .. tab:: Unix/macOS @@ -396,10 +420,10 @@ Installing from Wheels "Wheel" is a built, archive format that can greatly speed installation compared to building and installing from source archives. For more information, see the -:ref:`specification `. +:ref:specification . pip prefers Wheels where they are available. To disable this, use the -:ref:`--no-binary ` flag for :ref:`pip install`. +:ref:--no-binary flag for :ref:pip install. If no satisfactory wheels are found, pip will default to finding source archives. @@ -419,7 +443,7 @@ To install directly from a wheel archive: py -m pip install SomePackage-1.0-py2.py3-none-any.whl -To include optional dependencies provided in the ``provides_extras`` +To include optional dependencies provided in the `provides_extras` metadata in the wheel, you must add quotes around the install target name: @@ -437,11 +461,11 @@ name: .. note:: - In the future, the ``path[extras]`` syntax may become deprecated. It is - recommended to use :ref:`standard ` + In the future, the `path[extras]` syntax may become deprecated. It is + recommended to use :ref:standard syntax wherever possible. -For the cases where wheels are not available, pip offers :ref:`pip wheel` as a +For the cases where wheels are not available, pip offers :ref:pip wheel as a convenience, to build wheels for all your requirements and dependencies. To build wheels for your requirements and all their dependencies to a local @@ -461,7 +485,7 @@ directory: py -m pip install wheel py -m pip wheel --wheel-dir=/local/wheels -r requirements.txt -And *then* to install those requirements just using your local directory of +And then to install those requirements just using your local directory of wheels (and not from PyPI): .. tab:: Unix/macOS @@ -498,7 +522,7 @@ pip is able to uninstall most packages like so: pip also performs an automatic uninstall of an old version of a package before upgrading to a newer version. -For more information and examples, see the :ref:`pip uninstall` reference. +For more information and examples, see the :ref:pip uninstall reference. Listing Packages @@ -569,14 +593,14 @@ To show details about an installed package: Location: /my/env/lib/pythonx.x/site-packages Requires: Pygments, Jinja2, docutils -For more information and examples, see the :ref:`pip list` and :ref:`pip show` +For more information and examples, see the :ref:pip list and :ref:pip show reference pages. Searching for Packages ====================== -pip can search `PyPI`_ for packages using the ``pip search`` +pip can search `PyPI`_ for packages using the `pip search` command: .. tab:: Unix/macOS @@ -594,27 +618,27 @@ command: The query will be used to search the names and summaries of all packages. -For more information and examples, see the :ref:`pip search` reference. +For more information and examples, see the :ref:pip search reference. .. _`0-configuration`: .. rubric:: Configuration -This is now covered in :doc:`topics/configuration`. +This is now covered in :doc:topics/configuration. .. _`0-config-file`: .. rubric:: Config file -This is now covered in :doc:`topics/configuration`. +This is now covered in :doc:topics/configuration. .. _`0-environment-variables`: .. rubric:: Environment Variables -This is now covered in :doc:`topics/configuration`. +This is now covered in :doc:topics/configuration. .. _`0-config-precedence`: .. rubric:: Config Precedence -This is now covered in :doc:`topics/configuration`. +This is now covered in :doc:topics/configuration. Command Completion ================== @@ -637,11 +661,11 @@ To setup for powershell:: python -m pip completion --powershell | Out-File -Encoding default -Append $PROFILE -Alternatively, you can use the result of the ``completion`` command directly +Alternatively, you can use the result of the `completion` command directly with the eval function of your shell, e.g. by adding the following to your startup file:: - eval "`pip completion --bash`" + eval "pip completion --bash" @@ -668,7 +692,7 @@ First, download the archives that fulfill your requirements: py -m pip download --destination-directory DIR -r requirements.txt -Note that ``pip download`` will look in your wheel cache first, before +Note that `pip download` will look in your wheel cache first, before trying to download from PyPI. If you've never installed your requirements before, you won't have a wheel cache for those items. In that case, if some of your requirements don't come as wheels from PyPI, and you want wheels, then run @@ -687,7 +711,7 @@ this instead: py -m pip wheel --wheel-dir DIR -r requirements.txt Then, to install from local only, you'll be using :ref:`--find-links -` and :ref:`--no-index ` like so: +` and :ref:--no-index like so: .. tab:: Unix/macOS @@ -705,34 +729,34 @@ Then, to install from local only, you'll be using :ref:`--find-links "Only if needed" Recursive Upgrade ================================== -``pip install --upgrade`` now has a ``--upgrade-strategy`` option which +`pip install --upgrade` now has a `--upgrade-strategy` option which controls how pip handles upgrading of dependencies. There are 2 upgrade strategies supported: -- ``eager``: upgrades all dependencies regardless of whether they still satisfy +- `eager`: upgrades all dependencies regardless of whether they still satisfy the new parent requirements -- ``only-if-needed``: upgrades a dependency only if it does not satisfy the new +- `only-if-needed`: upgrades a dependency only if it does not satisfy the new parent requirements -The default strategy is ``only-if-needed``. This was changed in pip 10.0 due to -the breaking nature of ``eager`` when upgrading conflicting dependencies. +The default strategy is `only-if-needed`. This was changed in pip 10.0 due to +the breaking nature of `eager` when upgrading conflicting dependencies. -It is important to note that ``--upgrade`` affects *direct requirements* (e.g. +It is important to note that `--upgrade` affects direct requirements (e.g. those specified on the command-line or via a requirements file) while -``--upgrade-strategy`` affects *indirect requirements* (dependencies of direct +`--upgrade-strategy` affects indirect requirements (dependencies of direct requirements). -As an example, say ``SomePackage`` has a dependency, ``SomeDependency``, and +As an example, say `SomePackage` has a dependency, `SomeDependency`, and both of them are already installed but are not the latest available versions: -- ``pip install SomePackage``: will not upgrade the existing ``SomePackage`` or - ``SomeDependency``. -- ``pip install --upgrade SomePackage``: will upgrade ``SomePackage``, but not - ``SomeDependency`` (unless a minimum requirement is not met). -- ``pip install --upgrade SomePackage --upgrade-strategy=eager``: upgrades both - ``SomePackage`` and ``SomeDependency``. +- `pip install SomePackage`: will not upgrade the existing `SomePackage` or + `SomeDependency`. +- `pip install --upgrade SomePackage`: will upgrade `SomePackage`, but not + `SomeDependency` (unless a minimum requirement is not met). +- `pip install --upgrade SomePackage --upgrade-strategy=eager`: upgrades both + `SomePackage` and `SomeDependency`. -As an historic note, an earlier "fix" for getting the ``only-if-needed`` +As an historic note, an earlier "fix" for getting the `only-if-needed` behaviour was: .. tab:: Unix/macOS @@ -750,7 +774,7 @@ behaviour was: py -m pip install SomePackage -A proposal for an ``upgrade-all`` command is being considered as a safer +A proposal for an `upgrade-all` command is being considered as a safer alternative to the behaviour of eager upgrading. @@ -764,13 +788,13 @@ location that is specific to a user. The default location for each OS is explained in the python documentation for the `site.USER_BASE `_ variable. This mode of installation can be turned on by specifying the :ref:`--user -` option to ``pip install``. +` option to `pip install`. Moreover, the "user scheme" can be customized by setting the -``PYTHONUSERBASE`` environment variable, which updates the value of -``site.USER_BASE``. +`PYTHONUSERBASE` environment variable, which updates the value of +`site.USER_BASE`. -To install "SomePackage" into an environment with ``site.USER_BASE`` customized to +To install "SomePackage" into an environment with `site.USER_BASE` customized to '/myappenv', do the following: .. tab:: Unix/macOS @@ -787,27 +811,27 @@ To install "SomePackage" into an environment with ``site.USER_BASE`` customized set PYTHONUSERBASE=c:/myappenv py -m pip install --user SomePackage -``pip install --user`` follows four rules: +`pip install --user` follows four rules: -#. When globally installed packages are on the python path, and they *conflict* - with the installation requirements, they are ignored, and *not* +#. When globally installed packages are on the python path, and they conflict + with the installation requirements, they are ignored, and not uninstalled. -#. When globally installed packages are on the python path, and they *satisfy* +#. When globally installed packages are on the python path, and they satisfy the installation requirements, pip does nothing, and reports that requirement is satisfied (similar to how global packages can satisfy - requirements when installing packages in a ``--system-site-packages`` + requirements when installing packages in a `--system-site-packages` virtualenv). -#. pip will not perform a ``--user`` install in a ``--no-site-packages`` +#. pip will not perform a `--user` install in a `--no-site-packages` virtualenv (i.e. the default kind of virtualenv), due to the user site not being on the python path. The installation would be pointless. -#. In a ``--system-site-packages`` virtualenv, pip will not install a package +#. In a `--system-site-packages` virtualenv, pip will not install a package that conflicts with a package in the virtualenv site-packages. The --user installation would lack sys.path precedence and be pointless. To make the rules clearer, here are some examples: -From within a ``--no-site-packages`` virtualenv (i.e. the default kind): +From within a `--no-site-packages` virtualenv (i.e. the default kind): .. tab:: Unix/macOS @@ -824,7 +848,7 @@ From within a ``--no-site-packages`` virtualenv (i.e. the default kind): Can not perform a '--user' install. User site-packages are not visible in this virtualenv. -From within a ``--system-site-packages`` virtualenv where ``SomePackage==0.3`` +From within a `--system-site-packages` virtualenv where `SomePackage==0.3` is already installed in the virtualenv: .. tab:: Unix/macOS @@ -841,7 +865,7 @@ is already installed in the virtualenv: C:\> py -m pip install --user SomePackage==0.4 Will not install to the user site because it will lack sys.path precedence -From within a real python, where ``SomePackage`` is *not* installed globally: +From within a real python, where `SomePackage` is not installed globally: .. tab:: Unix/macOS @@ -859,8 +883,8 @@ From within a real python, where ``SomePackage`` is *not* installed globally: [...] Successfully installed SomePackage -From within a real python, where ``SomePackage`` *is* installed globally, but -is *not* the latest version: +From within a real python, where `SomePackage` is installed globally, but +is not the latest version: .. tab:: Unix/macOS @@ -884,7 +908,7 @@ is *not* the latest version: [...] Successfully installed SomePackage -From within a real python, where ``SomePackage`` *is* installed globally, and +From within a real python, where `SomePackage` is installed globally, and is the latest version: .. tab:: Unix/macOS @@ -921,12 +945,12 @@ is the latest version: .. _`0-ensuring-repeatability`: .. rubric:: Ensuring Repeatability -This is now covered in :doc:`../topics/repeatable-installs`. +This is now covered in :doc:../topics/repeatable-installs. .. _`0-fixing-conflicting-dependencies`: .. rubric:: Fixing conflicting dependencies -This is now covered in :doc:`../topics/dependency-resolution`. +This is now covered in :doc:../topics/dependency-resolution. .. _`Using pip from your program`: @@ -934,7 +958,7 @@ Using pip from your program =========================== As noted previously, pip is a command line program. While it is implemented in -Python, and so is available from your Python code via ``import pip``, you must +Python, and so is available from your Python code via `import pip`, you must not use pip's internal APIs in this way. There are a number of reasons for this: #. The pip code assumes that it is in sole control of the global state of the @@ -943,7 +967,7 @@ not use pip's internal APIs in this way. There are a number of reasons for this: the standard IO streams, without considering the possibility that user code might be affected. -#. pip's code is *not* thread safe. If you were to run pip in a thread, there +#. pip's code is not thread safe. If you were to run pip in a thread, there is no guarantee that either your code or pip's would work as you expect. #. pip assumes that once it has finished its work, the process will terminate. @@ -960,13 +984,13 @@ releases of pip. And we simply don't currently have the resources to even consider such a task. What this means in practice is that everything inside of pip is considered an -implementation detail. Even the fact that the import name is ``pip`` is subject +implementation detail. Even the fact that the import name is `pip` is subject to change without notice. While we do try not to break things as much as possible, all the internal APIs can change at any time, for any reason. It also -means that we generally *won't* fix issues that are a result of using pip in an +means that we generally won't fix issues that are a result of using pip in an unsupported way. -It should also be noted that installing packages into ``sys.path`` in a running +It should also be noted that installing packages into `sys.path` in a running Python process is something that should only be done with care. The import system caches certain data, and installing new packages while a program is running may not always behave as expected. In practice, there is rarely an @@ -975,7 +999,7 @@ issue, but it is something to be aware of. Having said all of the above, it is worth covering the options available if you decide that you do want to run pip from within your program. The most reliable approach, and the one that is fully supported, is to run pip in a subprocess. -This is easily done using the standard ``subprocess`` module:: +This is easily done using the standard `subprocess` module:: subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'my_package']) @@ -984,24 +1008,24 @@ We are using `freeze`_ here which outputs installed packages in requirements for reqs = subprocess.check_output([sys.executable, '-m', 'pip', 'freeze']) -To programmatically monitor download progress use the ``--progress-bar=raw`` option. -This will print lines to stdout in the format ``Progress CURRENT of TOTAL``, where -``CURRENT`` and ``TOTAL`` are integers and the unit is bytes. -If the real total is unknown then ``TOTAL`` is set to ``0``. Be aware that the -specific formatting of pip's outputs are *not* guaranteed to be the same in future versions. +To programmatically monitor download progress use the `--progress-bar=raw` option. +This will print lines to stdout in the format `Progress CURRENT of TOTAL`, where +`CURRENT` and `TOTAL` are integers and the unit is bytes. +If the real total is unknown then `TOTAL` is set to `0`. Be aware that the +specific formatting of pip's outputs are not guaranteed to be the same in future versions. If you don't want to use pip's command line functionality, but are rather trying to implement code that works with Python packages, their metadata, or PyPI, then you should consider other, supported, packages that offer this type of ability. Some examples that you could consider include: -* ``packaging`` - Utilities to work with standard package metadata (versions, +* `packaging` - Utilities to work with standard package metadata (versions, requirements, etc.) -* ``importlib.metadata`` in the Python stdlib - Functions for querying what +* `importlib.metadata` in the Python stdlib - Functions for querying what packages the user has installed on their system. -* ``distlib`` - Packaging and distribution utilities (including functions for +* `distlib` - Packaging and distribution utilities (including functions for interacting with PyPI). .. _changes-to-the-pip-dependency-resolver-in-20-2-2020: @@ -1031,7 +1055,7 @@ The big change in this release is to the pip dependency resolver within pip. Computers need to know the right order to install pieces of software -("to install ``x``, you need to install ``y`` first"). So, when Python +("to install `x`, you need to install `y` first"). So, when Python programmers share software as packages, they have to precisely describe those installation prerequisites, and pip needs to navigate tricky situations where it's getting conflicting instructions. This new @@ -1040,19 +1064,19 @@ logic, and make pip easier for you to use and troubleshoot. The most significant changes to the resolver are: -* It will **reduce inconsistency**: it will *no longer install a +* It will *reduce inconsistency*: it will *no longer install a combination of packages that is mutually inconsistent*. In older versions of pip, it is possible for pip to install a package which does not satisfy the declared requirements of another installed package. For example, in pip 20.0, ``pip install "six<1.12" "virtualenv==20.0.2"`` does the wrong thing, “successfully” installing - ``six==1.11``, even though ``virtualenv==20.0.2`` requires - ``six>=1.12.0,<2`` (`defined here + `six==1.11`, even though `virtualenv==20.0.2` requires + `six>=1.12.0,<2` (`defined here `__). The new resolver, instead, outright rejects installing anything if it gets that input. -* It will be **stricter** - if you ask pip to install two packages with +* It will be *stricter* - if you ask pip to install two packages with incompatible requirements, it will refuse (rather than installing a broken combination, like it did in previous versions). @@ -1061,18 +1085,18 @@ incompatible or inconsistent requirements combinations, now's a good time to fix the underlying problem in the packages, because pip will be stricter from here on out. -This also means that, when you run a ``pip install`` command, pip only +This also means that, when you run a `pip install` command, pip only considers the packages you are installing in that command, and **may break already-installed packages**. It will not guarantee that your -environment will be consistent all the time. If you ``pip install x`` -and then ``pip install y``, it's possible that the version of ``y`` +environment will be consistent all the time. If you `pip install x` +and then `pip install y`, it's possible that the version of `y` you get will be different than it would be if you had run ``pip install x y`` in a single command. We are considering changing this -behavior (per :issue:`7744`) and would like your thoughts on what +behavior (per :issue:7744) and would like your thoughts on what pip's behavior should be; please answer `our survey on upgrades that create conflicts`_. -We are also changing our support for :ref:`Constraints Files`, +We are also changing our support for :ref:Constraints Files, editable installs, and related functionality. We did a fairly comprehensive overhaul and stripped constraints files down to being purely a way to specify global (version) limits for packages, and so @@ -1081,23 +1105,23 @@ errors. Specifically: * Constraints don't override the existing requirements; they simply constrain what versions are visible as input to the resolver (see - :issue:`9020`) -* Providing an editable requirement (``-e .``) does not cause pip to - ignore version specifiers or constraints (see :issue:`8076`), and if + :issue:9020) +* Providing an editable requirement (`-e .`) does not cause pip to + ignore version specifiers or constraints (see :issue:8076), and if you have a conflict between a pinned requirement and a local directory then pip will indicate that it cannot find a version - satisfying both (see :issue:`8307`) + satisfying both (see :issue:8307) * Hash-checking mode requires that all requirements are specified as a - ``==`` match on a version and may not work well in combination with - constraints (see :issue:`9020` and :issue:`8792`) + `==` match on a version and may not work well in combination with + constraints (see :issue:9020 and :issue:8792) * If necessary to satisfy constraints, pip will happily reinstall packages, upgrading or downgrading, without needing any additional - command-line options (see :issue:`8115` and :doc:`development/architecture/upgrade-options`) -* Unnamed requirements are not allowed as constraints (see :issue:`6628` and :issue:`8210`) -* Links are not allowed as constraints (see :issue:`8253`) -* Constraints cannot have extras (see :issue:`6628`) + command-line options (see :issue:8115 and :doc:development/architecture/upgrade-options) +* Unnamed requirements are not allowed as constraints (see :issue:6628 and :issue:8210) +* Links are not allowed as constraints (see :issue:8253) +* Constraints cannot have extras (see :issue:6628) -Per our :ref:`Python 2 Support` policy, pip 20.3 users who are using +Per our :ref:Python 2 Support policy, pip 20.3 users who are using Python 2 will use the legacy resolver by default. Python 2 users should upgrade to Python 3 as soon as possible, since in pip 21.0 in January 2021, pip dropped support for Python 2 altogether. @@ -1106,17 +1130,17 @@ January 2021, pip dropped support for Python 2 altogether. How to upgrade and migrate -------------------------- -1. **Install pip 20.3** with ``python -m pip install --upgrade pip``. +1. *Install pip 20.3* with `python -m pip install --upgrade pip`. -2. **Validate your current environment** by running ``pip check``. This +2. *Validate your current environment* by running `pip check`. This will report if you have any inconsistencies in your set of installed packages. Having a clean installation will make it much less likely that you will hit issues with the new resolver (and may address hidden problems in your current environment!). If you run - ``pip check`` and run into stuff you can’t figure out, please `ask + `pip check` and run into stuff you can’t figure out, please `ask for help in our issue tracker or chat `__. -3. **Test the new version of pip**. +3. *Test the new version of pip*. While we have tried to make sure that pip’s test suite covers as many cases as we can, we are very aware that there are people using @@ -1124,11 +1148,11 @@ How to upgrade and migrate not be able to cover all of those without your help. - If you use pip to install your software, try out the new resolver - and let us know if it works for you with ``pip install``. Try: + and let us know if it works for you with `pip install`. Try: - installing several packages simultaneously - - re-creating an environment using a ``requirements.txt`` file - - using ``pip install --force-reinstall`` to check whether + - re-creating an environment using a `requirements.txt` file + - using `pip install --force-reinstall` to check whether it does what you think it should - using constraints files - the "Setups to test with special attention" and "Examples to try" below @@ -1149,23 +1173,23 @@ How to upgrade and migrate deliver part of your functionality, please test your integration with pip 20.3. -4. **Troubleshoot and try these workarounds if necessary.** +4. *Troubleshoot and try these workarounds if necessary.* - If pip is taking longer to install packages, read :doc:`Dependency resolution backtracking ` for ways to reduce the time pip spends backtracking due to dependency conflicts. - If you don't want pip to actually resolve dependencies, use the - ``--no-deps`` option. This is useful when you have a set of package + `--no-deps` option. This is useful when you have a set of package versions that work together in reality, even though their metadata says that they conflict. For guidance on a long-term fix, read - :ref:`Fixing conflicting dependencies`. + :ref:Fixing conflicting dependencies. - If you run into resolution errors and need a workaround while you're fixing their root causes, you can choose the old resolver behavior using - the flag ``--use-deprecated=legacy-resolver``. This will work until we + the flag `--use-deprecated=legacy-resolver`. This will work until we release pip 21.0 (see - :ref:`Deprecation timeline for 2020 resolver changes`). + :ref:Deprecation timeline for 2020 resolver changes). -5. **Please report bugs** through the `resolver testing survey`_. +5. *Please report bugs* through the `resolver testing survey`_. Setups to test with special attention @@ -1175,15 +1199,15 @@ Setups to test with special attention * Installation workflows that involve multiple requirements files -* Requirements files that include hashes (:ref:`hash-checking mode`) - or pinned dependencies (perhaps as output from ``pip-compile`` within - ``pip-tools``) +* Requirements files that include hashes (:ref:hash-checking mode) + or pinned dependencies (perhaps as output from `pip-compile` within + `pip-tools`) -* Using :ref:`Constraints Files` +* Using :ref:Constraints Files * Continuous integration/continuous deployment setups -* Installing from any kind of version control systems (i.e., Git, Subversion, Mercurial, or CVS), per :doc:`topics/vcs-support` +* Installing from any kind of version control systems (i.e., Git, Subversion, Mercurial, or CVS), per :doc:topics/vcs-support * Installing from source code held in local directories @@ -1193,21 +1217,21 @@ Examples to try Install: * `tensorflow`_ -* ``hacking`` -* ``pycodestyle`` -* ``pandas`` -* ``tablib`` -* ``elasticsearch`` and ``requests`` together -* ``six`` and ``cherrypy`` together -* ``pip install flake8-import-order==0.17.1 flake8==3.5.0 --use-feature=2020-resolver`` -* ``pip install tornado==5.0 sprockets.http==1.5.0 --use-feature=2020-resolver`` +* `hacking` +* `pycodestyle` +* `pandas` +* `tablib` +* `elasticsearch` and `requests` together +* `six` and `cherrypy` together +* `pip install flake8-import-order==0.17.1 flake8==3.5.0 --use-feature=2020-resolver` +* `pip install tornado==5.0 sprockets.http==1.5.0 --use-feature=2020-resolver` Try: -* ``pip install`` -* ``pip uninstall`` -* ``pip check`` -* ``pip cache`` +* `pip install` +* `pip uninstall` +* `pip check` +* `pip cache` Tell us about @@ -1237,32 +1261,32 @@ Deprecation timeline -------------------- We plan for the resolver changeover to proceed as follows, using -:ref:`Feature Flags` and following our :ref:`Release Cadence`: +:ref:Feature Flags and following our :ref:Release Cadence: * pip 20.1: an alpha version of the new resolver was available, opt-in, using the optional flag - ``--unstable-feature=resolver``. pip defaulted to legacy + `--unstable-feature=resolver`. pip defaulted to legacy behavior. * pip 20.2: a beta of the new resolver was available, opt-in, using - the flag ``--use-feature=2020-resolver``. pip defaulted to legacy + the flag `--use-feature=2020-resolver`. pip defaulted to legacy behavior. Users of pip 20.2 who want pip to default to using the new resolver can run ``pip config set global.use-feature 2020-resolver`` (for more on that and the alternate - ``PIP_USE_FEATURE`` environment variable option, see `issue + `PIP_USE_FEATURE` environment variable option, see `issue 8661`_). * pip 20.3: pip defaults to the new resolver in Python 3 environments, but a user can opt-out and choose the old resolver behavior, - using the flag ``--use-deprecated=legacy-resolver``. In Python 2 + using the flag `--use-deprecated=legacy-resolver`. In Python 2 environments, pip defaults to the old resolver, and the new one is - available using the flag ``--use-feature=2020-resolver``. + available using the flag `--use-feature=2020-resolver`. * pip 21.0: pip uses new resolver by default, and the old resolver is no longer supported. It will be removed after a currently undecided amount of time, as the removal is dependent on pip's volunteer maintainers' availability. Python 2 support is removed per our - :ref:`Python 2 Support` policy. + :ref:Python 2 Support policy. Since this work will not change user-visible behavior described in the pip documentation, this change is not covered by the :ref:`Deprecation @@ -1271,7 +1295,7 @@ Policy`. .. attention:: The legacy resolver is deprecated and unsupported. New features, such - as :doc:`reference/installation-report`, will not work with the + as :doc:reference/installation-report, will not work with the legacy resolver and this resolver will be removed in a future release. @@ -1282,7 +1306,7 @@ As discussed in `our announcement on the PSF blog`_, the pip team are in the process of developing a new "dependency resolver" (the part of pip that works out what to install based on your requirements). -We're tracking our rollout in :issue:`6536` and you can watch for +We're tracking our rollout in :issue:6536 and you can watch for announcements on the `low-traffic packaging announcements list`_ and `the official Python blog`_. @@ -1300,4 +1324,4 @@ announcements on the `low-traffic packaging announcements list`_ and .. _`0-using-system-trust-stores-for-verifying-https`: .. rubric:: Using system trust stores for verifying HTTPS -This is now covered in :doc:`topics/https-certificates`. +This is now covered in :doc:topics/https-certificates. \ No newline at end of file diff --git a/news/13690.doc.rst b/news/13690.doc.rst new file mode 100644 index 00000000000..2bf680a8bb3 --- /dev/null +++ b/news/13690.doc.rst @@ -0,0 +1,2 @@ +### Added +- beginner example for Running pip section in user guide (#13690) — Mennaalazaz \ No newline at end of file From 5d7fcb8965f893155f6c274c20aae220a00746d8 Mon Sep 17 00:00:00 2001 From: Mennaalazaz <162923696+Mennaalazaz@users.noreply.github.com> Date: Thu, 11 Dec 2025 13:27:57 +0200 Subject: [PATCH 2/3] Add beginner example in Running pip section --- docs/html/user_guide.rst | 370 +++++++++++++++++++-------------------- 1 file changed, 183 insertions(+), 187 deletions(-) diff --git a/docs/html/user_guide.rst b/docs/html/user_guide.rst index 1ad7ff079cd..f74061ef9ce 100644 --- a/docs/html/user_guide.rst +++ b/docs/html/user_guide.rst @@ -8,14 +8,14 @@ User Guide to consider if this content can live on its own, within a topic guide or a reference page. - There is active effort being put toward reducing the amount of content on + There is active effort being put toward *reducing* the amount of content on this specific page (https://github.com/pypa/pip/issues/9475) and moving it into more focused single-page documents that cover that specific topic. Running pip =========== -pip is a command line program. When you install pip, a `pip` command is added +pip is a command line program. When you install pip, a ``pip`` command is added to your system, which can be run from the command prompt as follows: .. tab:: Unix/macOS @@ -24,9 +24,9 @@ to your system, which can be run from the command prompt as follows: python -m pip - `python -m pip` executes pip using the Python interpreter you - specified as python. So `/usr/bin/python3.7 -m pip` means - you are executing pip for your interpreter located at `/usr/bin/python3.7`. + ``python -m pip`` executes pip using the Python interpreter you + specified as python. So ``/usr/bin/python3.7 -m pip`` means + you are executing pip for your interpreter located at ``/usr/bin/python3.7``. .. tab:: Windows @@ -34,7 +34,7 @@ to your system, which can be run from the command prompt as follows: py -m pip - `py -m pip` executes pip using the latest Python interpreter you + ``py -m pip`` executes pip using the latest Python interpreter you have installed. For more details, read the `Python Windows launcher`_ docs. .. note:: @@ -46,21 +46,17 @@ to your system, which can be run from the command prompt as follows: .. tab:: Unix/macOS .. code-block:: shell - python -m pip install requests - This installs the popular `requests` library using the Python interpreter currently in use. .. tab:: Windows .. code-block:: shell - py -m pip install requests - This installs the `requests` library using the latest Python interpreter available on your system. - + Installing Packages =================== @@ -88,24 +84,24 @@ Specifiers` py -m pip install SomePackage==1.0.4 # specific version py -m pip install 'SomePackage>=1.0.4' # minimum version -For more information and examples, see the :ref:pip install reference. +For more information and examples, see the :ref:`pip install` reference. .. _PyPI: https://pypi.org/ .. _`0-basic-authentication-credentials`: .. rubric:: Basic Authentication Credentials -This is now covered in :doc:topics/authentication. +This is now covered in :doc:`topics/authentication`. .. _`0-netrc-support`: .. rubric:: netrc Support -This is now covered in :doc:topics/authentication. +This is now covered in :doc:`topics/authentication`. .. _`0-keyring-support`: .. rubric:: Keyring Support -This is now covered in :doc:topics/authentication. +This is now covered in :doc:`topics/authentication`. Using a Proxy Server ==================== @@ -115,12 +111,12 @@ in many corporate environments requires an outbound HTTP proxy server. pip can be configured to connect through a proxy server in various ways: -* using the `--proxy` command-line option to specify a proxy in the form - `scheme://[user:passwd@]proxy.server:port` -* using `proxy` in a :ref:config-file -* by setting the standard environment-variables `http_proxy`, `https_proxy` - and `no_proxy`. -* using the environment variable `PIP_USER_AGENT_USER_DATA` to include +* using the ``--proxy`` command-line option to specify a proxy in the form + ``scheme://[user:passwd@]proxy.server:port`` +* using ``proxy`` in a :ref:`config-file` +* by setting the standard environment-variables ``http_proxy``, ``https_proxy`` + and ``no_proxy``. +* using the environment variable ``PIP_USER_AGENT_USER_DATA`` to include a JSON-encoded string in the user-agent variable used in pip's requests. @@ -131,7 +127,7 @@ Requirements Files ================== "Requirements files" are files containing a list of items to be -installed using :ref:pip install like so: +installed using :ref:`pip install` like so: .. tab:: Unix/macOS @@ -145,9 +141,9 @@ installed using :ref:pip install like so: py -m pip install -r requirements.txt -Details on the format of the files are here: :ref:requirements-file-format. +Details on the format of the files are here: :ref:`requirements-file-format`. -Logically, a Requirements file is just a list of :ref:pip install arguments +Logically, a Requirements file is just a list of :ref:`pip install` arguments placed in a file. Note that you should not rely on the items in the file being installed by pip in any particular order. @@ -157,10 +153,10 @@ be stored and served in a centralized place. In practice, there are 4 common uses of Requirements files: -1. Requirements files are used to hold the result from :ref:pip freeze for the - purpose of achieving :doc:topics/repeatable-installs. In +1. Requirements files are used to hold the result from :ref:`pip freeze` for the + purpose of achieving :doc:`topics/repeatable-installs`. In this case, your requirement file contains a pinned version of everything that - was installed when `pip freeze` was run. + was installed when ``pip freeze`` was run. .. tab:: Unix/macOS @@ -179,11 +175,11 @@ In practice, there are 4 common uses of Requirements files: 2. Requirements files are used to force pip to properly resolve dependencies. pip 20.2 and earlier `doesn't have true dependency resolution `_, but instead simply uses the first - specification it finds for a project. E.g. if `pkg1` requires - `pkg3>=1.0` and `pkg2` requires `pkg3>=1.0,<=2.0`, and if `pkg1` is - resolved first, pip will only use `pkg3>=1.0`, and could easily end up - installing a version of `pkg3` that conflicts with the needs of `pkg2`. - To solve this problem, you can place `pkg3>=1.0,<=2.0` (i.e. the correct + specification it finds for a project. E.g. if ``pkg1`` requires + ``pkg3>=1.0`` and ``pkg2`` requires ``pkg3>=1.0,<=2.0``, and if ``pkg1`` is + resolved first, pip will only use ``pkg3>=1.0``, and could easily end up + installing a version of ``pkg3`` that conflicts with the needs of ``pkg2``. + To solve this problem, you can place ``pkg3>=1.0,<=2.0`` (i.e. the correct specification) into your requirements file directly along with the other top level requirements. Like so:: @@ -192,8 +188,8 @@ In practice, there are 4 common uses of Requirements files: pkg3>=1.0,<=2.0 3. Requirements files are used to force pip to install an alternate version of a - sub-dependency. For example, suppose `ProjectA` in your requirements file - requires `ProjectB`, but the latest version (v1.3) has a bug, you can force + sub-dependency. For example, suppose ``ProjectA`` in your requirements file + requires ``ProjectB``, but the latest version (v1.3) has a bug, you can force pip to accept earlier versions like so:: ProjectA @@ -201,27 +197,27 @@ In practice, there are 4 common uses of Requirements files: 4. Requirements files are used to override a dependency with a local patch that lives in version control. For example, suppose a dependency - `SomeDependency` from PyPI has a bug, and you can't wait for an upstream + ``SomeDependency`` from PyPI has a bug, and you can't wait for an upstream fix. You could clone/copy the src, make the fix, and place it in VCS with the tag - `sometag`. You'd reference it in your requirements file with a line like + ``sometag``. You'd reference it in your requirements file with a line like so:: SomeDependency @ git+https://myvcs.com/some_dependency@sometag - If `SomeDependency` was previously a top-level requirement in your - requirements file, then *replace* that line with the new line. If - `SomeDependency` is a sub-dependency, then *add* the new line. + If ``SomeDependency`` was previously a top-level requirement in your + requirements file, then **replace** that line with the new line. If + ``SomeDependency`` is a sub-dependency, then **add** the new line. It's important to be clear that pip determines package dependencies using -the project metadata (typically in `pyproject.toml` or `setup.py`), -not by discovering `requirements.txt` files embedded in projects. +the project metadata (typically in ``pyproject.toml`` or ``setup.py``), +not by discovering ``requirements.txt`` files embedded in projects. See also: -* :ref:requirements-file-format -* :ref:pip freeze +* :ref:`requirements-file-format` +* :ref:`pip freeze` * `"setup.py vs requirements.txt" (an article by Donald Stufft) `_ @@ -234,7 +230,7 @@ Constraints Files Constraints files are requirements files that only control which version of a requirement is installed, not whether it is installed or not. Their syntax and -contents is a subset of :ref:Requirements Files, with several kinds of syntax +contents is a subset of :ref:`Requirements Files`, with several kinds of syntax not allowed: constraints must have a name, they cannot be editable, and they cannot specify extras. In terms of semantics, there is one key difference: Including a package in a constraints file does not trigger installation of the @@ -294,7 +290,7 @@ constraints only influence the versions of packages available during the build process. This is useful when you need to constrain build dependencies -(such as `setuptools`, `cython`, etc.) without affecting the +(such as ``setuptools``, ``cython``, etc.) without affecting the final installed environment. Use build constraints like so: @@ -311,7 +307,7 @@ Use build constraints like so: py -m pip install --build-constraint build-constraints.txt SomePackage -Example build constraints file (`build-constraints.txt`): +Example build constraints file (``build-constraints.txt``): .. code-block:: text @@ -328,11 +324,11 @@ Dependency Groups ================= "Dependency Groups" are lists of items to be installed stored in a -`pyproject.toml` file. +``pyproject.toml`` file. A dependency group is logically just a list of requirements, similar to the -contents of :ref:Requirements Files. Unlike requirements files, dependency -groups cannot contain non-package arguments for :ref:pip install. +contents of :ref:`Requirements Files`. Unlike requirements files, dependency +groups cannot contain non-package arguments for :ref:`pip install`. Groups can be declared like so: @@ -345,7 +341,7 @@ Groups can be declared like so: "pkg2", ] -and installed with :ref:pip install like so: +and installed with :ref:`pip install` like so: .. tab:: Unix/macOS @@ -359,20 +355,20 @@ and installed with :ref:pip install like so: py -m pip install --group groupA -Full details on the contents of `[dependency-groups]` and more examples are -available in :ref:the specification documentation . +Full details on the contents of ``[dependency-groups]`` and more examples are +available in :ref:`the specification documentation `. .. note:: Dependency Groups are defined by a standard, and therefore do not support - `pip`-specific syntax for requirements, only :ref:`standard dependency + ``pip``-specific syntax for requirements, only :ref:`standard dependency specifiers `. -`pip` does not search projects or directories to discover `pyproject.toml` -files. The `--group` option is used to pass the path to the file, +``pip`` does not search projects or directories to discover ``pyproject.toml`` +files. The ``--group`` option is used to pass the path to the file, and if the path is omitted, as in the example above, it defaults to -`pyproject.toml` in the current directory. Using explicit paths, -:ref:pip install can use a file from another directory. For example: +``pyproject.toml`` in the current directory. Using explicit paths, +:ref:`pip install` can use a file from another directory. For example: .. tab:: Unix/macOS @@ -396,7 +392,7 @@ at once. For example, with a directory structure like so:: + sub2/ - pyproject.toml -it is possible to install, from the `project/` directory, groups from the +it is possible to install, from the ``project/`` directory, groups from the subprojects thusly: .. tab:: Unix/macOS @@ -420,10 +416,10 @@ Installing from Wheels "Wheel" is a built, archive format that can greatly speed installation compared to building and installing from source archives. For more information, see the -:ref:specification . +:ref:`specification `. pip prefers Wheels where they are available. To disable this, use the -:ref:--no-binary flag for :ref:pip install. +:ref:`--no-binary ` flag for :ref:`pip install`. If no satisfactory wheels are found, pip will default to finding source archives. @@ -443,7 +439,7 @@ To install directly from a wheel archive: py -m pip install SomePackage-1.0-py2.py3-none-any.whl -To include optional dependencies provided in the `provides_extras` +To include optional dependencies provided in the ``provides_extras`` metadata in the wheel, you must add quotes around the install target name: @@ -461,11 +457,11 @@ name: .. note:: - In the future, the `path[extras]` syntax may become deprecated. It is - recommended to use :ref:standard + In the future, the ``path[extras]`` syntax may become deprecated. It is + recommended to use :ref:`standard ` syntax wherever possible. -For the cases where wheels are not available, pip offers :ref:pip wheel as a +For the cases where wheels are not available, pip offers :ref:`pip wheel` as a convenience, to build wheels for all your requirements and dependencies. To build wheels for your requirements and all their dependencies to a local @@ -485,7 +481,7 @@ directory: py -m pip install wheel py -m pip wheel --wheel-dir=/local/wheels -r requirements.txt -And then to install those requirements just using your local directory of +And *then* to install those requirements just using your local directory of wheels (and not from PyPI): .. tab:: Unix/macOS @@ -522,7 +518,7 @@ pip is able to uninstall most packages like so: pip also performs an automatic uninstall of an old version of a package before upgrading to a newer version. -For more information and examples, see the :ref:pip uninstall reference. +For more information and examples, see the :ref:`pip uninstall` reference. Listing Packages @@ -593,14 +589,14 @@ To show details about an installed package: Location: /my/env/lib/pythonx.x/site-packages Requires: Pygments, Jinja2, docutils -For more information and examples, see the :ref:pip list and :ref:pip show +For more information and examples, see the :ref:`pip list` and :ref:`pip show` reference pages. Searching for Packages ====================== -pip can search `PyPI`_ for packages using the `pip search` +pip can search `PyPI`_ for packages using the ``pip search`` command: .. tab:: Unix/macOS @@ -618,27 +614,27 @@ command: The query will be used to search the names and summaries of all packages. -For more information and examples, see the :ref:pip search reference. +For more information and examples, see the :ref:`pip search` reference. .. _`0-configuration`: .. rubric:: Configuration -This is now covered in :doc:topics/configuration. +This is now covered in :doc:`topics/configuration`. .. _`0-config-file`: .. rubric:: Config file -This is now covered in :doc:topics/configuration. +This is now covered in :doc:`topics/configuration`. .. _`0-environment-variables`: .. rubric:: Environment Variables -This is now covered in :doc:topics/configuration. +This is now covered in :doc:`topics/configuration`. .. _`0-config-precedence`: .. rubric:: Config Precedence -This is now covered in :doc:topics/configuration. +This is now covered in :doc:`topics/configuration`. Command Completion ================== @@ -661,11 +657,11 @@ To setup for powershell:: python -m pip completion --powershell | Out-File -Encoding default -Append $PROFILE -Alternatively, you can use the result of the `completion` command directly +Alternatively, you can use the result of the ``completion`` command directly with the eval function of your shell, e.g. by adding the following to your startup file:: - eval "pip completion --bash" + eval "`pip completion --bash`" @@ -692,7 +688,7 @@ First, download the archives that fulfill your requirements: py -m pip download --destination-directory DIR -r requirements.txt -Note that `pip download` will look in your wheel cache first, before +Note that ``pip download`` will look in your wheel cache first, before trying to download from PyPI. If you've never installed your requirements before, you won't have a wheel cache for those items. In that case, if some of your requirements don't come as wheels from PyPI, and you want wheels, then run @@ -711,7 +707,7 @@ this instead: py -m pip wheel --wheel-dir DIR -r requirements.txt Then, to install from local only, you'll be using :ref:`--find-links -` and :ref:--no-index like so: +` and :ref:`--no-index ` like so: .. tab:: Unix/macOS @@ -729,34 +725,34 @@ Then, to install from local only, you'll be using :ref:`--find-links "Only if needed" Recursive Upgrade ================================== -`pip install --upgrade` now has a `--upgrade-strategy` option which +``pip install --upgrade`` now has a ``--upgrade-strategy`` option which controls how pip handles upgrading of dependencies. There are 2 upgrade strategies supported: -- `eager`: upgrades all dependencies regardless of whether they still satisfy +- ``eager``: upgrades all dependencies regardless of whether they still satisfy the new parent requirements -- `only-if-needed`: upgrades a dependency only if it does not satisfy the new +- ``only-if-needed``: upgrades a dependency only if it does not satisfy the new parent requirements -The default strategy is `only-if-needed`. This was changed in pip 10.0 due to -the breaking nature of `eager` when upgrading conflicting dependencies. +The default strategy is ``only-if-needed``. This was changed in pip 10.0 due to +the breaking nature of ``eager`` when upgrading conflicting dependencies. -It is important to note that `--upgrade` affects direct requirements (e.g. +It is important to note that ``--upgrade`` affects *direct requirements* (e.g. those specified on the command-line or via a requirements file) while -`--upgrade-strategy` affects indirect requirements (dependencies of direct +``--upgrade-strategy`` affects *indirect requirements* (dependencies of direct requirements). -As an example, say `SomePackage` has a dependency, `SomeDependency`, and +As an example, say ``SomePackage`` has a dependency, ``SomeDependency``, and both of them are already installed but are not the latest available versions: -- `pip install SomePackage`: will not upgrade the existing `SomePackage` or - `SomeDependency`. -- `pip install --upgrade SomePackage`: will upgrade `SomePackage`, but not - `SomeDependency` (unless a minimum requirement is not met). -- `pip install --upgrade SomePackage --upgrade-strategy=eager`: upgrades both - `SomePackage` and `SomeDependency`. +- ``pip install SomePackage``: will not upgrade the existing ``SomePackage`` or + ``SomeDependency``. +- ``pip install --upgrade SomePackage``: will upgrade ``SomePackage``, but not + ``SomeDependency`` (unless a minimum requirement is not met). +- ``pip install --upgrade SomePackage --upgrade-strategy=eager``: upgrades both + ``SomePackage`` and ``SomeDependency``. -As an historic note, an earlier "fix" for getting the `only-if-needed` +As an historic note, an earlier "fix" for getting the ``only-if-needed`` behaviour was: .. tab:: Unix/macOS @@ -774,7 +770,7 @@ behaviour was: py -m pip install SomePackage -A proposal for an `upgrade-all` command is being considered as a safer +A proposal for an ``upgrade-all`` command is being considered as a safer alternative to the behaviour of eager upgrading. @@ -788,13 +784,13 @@ location that is specific to a user. The default location for each OS is explained in the python documentation for the `site.USER_BASE `_ variable. This mode of installation can be turned on by specifying the :ref:`--user -` option to `pip install`. +` option to ``pip install``. Moreover, the "user scheme" can be customized by setting the -`PYTHONUSERBASE` environment variable, which updates the value of -`site.USER_BASE`. +``PYTHONUSERBASE`` environment variable, which updates the value of +``site.USER_BASE``. -To install "SomePackage" into an environment with `site.USER_BASE` customized to +To install "SomePackage" into an environment with ``site.USER_BASE`` customized to '/myappenv', do the following: .. tab:: Unix/macOS @@ -811,27 +807,27 @@ To install "SomePackage" into an environment with `site.USER_BASE` customized to set PYTHONUSERBASE=c:/myappenv py -m pip install --user SomePackage -`pip install --user` follows four rules: +``pip install --user`` follows four rules: -#. When globally installed packages are on the python path, and they conflict - with the installation requirements, they are ignored, and not +#. When globally installed packages are on the python path, and they *conflict* + with the installation requirements, they are ignored, and *not* uninstalled. -#. When globally installed packages are on the python path, and they satisfy +#. When globally installed packages are on the python path, and they *satisfy* the installation requirements, pip does nothing, and reports that requirement is satisfied (similar to how global packages can satisfy - requirements when installing packages in a `--system-site-packages` + requirements when installing packages in a ``--system-site-packages`` virtualenv). -#. pip will not perform a `--user` install in a `--no-site-packages` +#. pip will not perform a ``--user`` install in a ``--no-site-packages`` virtualenv (i.e. the default kind of virtualenv), due to the user site not being on the python path. The installation would be pointless. -#. In a `--system-site-packages` virtualenv, pip will not install a package +#. In a ``--system-site-packages`` virtualenv, pip will not install a package that conflicts with a package in the virtualenv site-packages. The --user installation would lack sys.path precedence and be pointless. To make the rules clearer, here are some examples: -From within a `--no-site-packages` virtualenv (i.e. the default kind): +From within a ``--no-site-packages`` virtualenv (i.e. the default kind): .. tab:: Unix/macOS @@ -848,7 +844,7 @@ From within a `--no-site-packages` virtualenv (i.e. the default kind): Can not perform a '--user' install. User site-packages are not visible in this virtualenv. -From within a `--system-site-packages` virtualenv where `SomePackage==0.3` +From within a ``--system-site-packages`` virtualenv where ``SomePackage==0.3`` is already installed in the virtualenv: .. tab:: Unix/macOS @@ -865,7 +861,7 @@ is already installed in the virtualenv: C:\> py -m pip install --user SomePackage==0.4 Will not install to the user site because it will lack sys.path precedence -From within a real python, where `SomePackage` is not installed globally: +From within a real python, where ``SomePackage`` is *not* installed globally: .. tab:: Unix/macOS @@ -883,8 +879,8 @@ From within a real python, where `SomePackage` is not installed globally: [...] Successfully installed SomePackage -From within a real python, where `SomePackage` is installed globally, but -is not the latest version: +From within a real python, where ``SomePackage`` *is* installed globally, but +is *not* the latest version: .. tab:: Unix/macOS @@ -908,7 +904,7 @@ is not the latest version: [...] Successfully installed SomePackage -From within a real python, where `SomePackage` is installed globally, and +From within a real python, where ``SomePackage`` *is* installed globally, and is the latest version: .. tab:: Unix/macOS @@ -945,12 +941,12 @@ is the latest version: .. _`0-ensuring-repeatability`: .. rubric:: Ensuring Repeatability -This is now covered in :doc:../topics/repeatable-installs. +This is now covered in :doc:`../topics/repeatable-installs`. .. _`0-fixing-conflicting-dependencies`: .. rubric:: Fixing conflicting dependencies -This is now covered in :doc:../topics/dependency-resolution. +This is now covered in :doc:`../topics/dependency-resolution`. .. _`Using pip from your program`: @@ -958,7 +954,7 @@ Using pip from your program =========================== As noted previously, pip is a command line program. While it is implemented in -Python, and so is available from your Python code via `import pip`, you must +Python, and so is available from your Python code via ``import pip``, you must not use pip's internal APIs in this way. There are a number of reasons for this: #. The pip code assumes that it is in sole control of the global state of the @@ -967,7 +963,7 @@ not use pip's internal APIs in this way. There are a number of reasons for this: the standard IO streams, without considering the possibility that user code might be affected. -#. pip's code is not thread safe. If you were to run pip in a thread, there +#. pip's code is *not* thread safe. If you were to run pip in a thread, there is no guarantee that either your code or pip's would work as you expect. #. pip assumes that once it has finished its work, the process will terminate. @@ -984,13 +980,13 @@ releases of pip. And we simply don't currently have the resources to even consider such a task. What this means in practice is that everything inside of pip is considered an -implementation detail. Even the fact that the import name is `pip` is subject +implementation detail. Even the fact that the import name is ``pip`` is subject to change without notice. While we do try not to break things as much as possible, all the internal APIs can change at any time, for any reason. It also -means that we generally won't fix issues that are a result of using pip in an +means that we generally *won't* fix issues that are a result of using pip in an unsupported way. -It should also be noted that installing packages into `sys.path` in a running +It should also be noted that installing packages into ``sys.path`` in a running Python process is something that should only be done with care. The import system caches certain data, and installing new packages while a program is running may not always behave as expected. In practice, there is rarely an @@ -999,7 +995,7 @@ issue, but it is something to be aware of. Having said all of the above, it is worth covering the options available if you decide that you do want to run pip from within your program. The most reliable approach, and the one that is fully supported, is to run pip in a subprocess. -This is easily done using the standard `subprocess` module:: +This is easily done using the standard ``subprocess`` module:: subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'my_package']) @@ -1008,24 +1004,24 @@ We are using `freeze`_ here which outputs installed packages in requirements for reqs = subprocess.check_output([sys.executable, '-m', 'pip', 'freeze']) -To programmatically monitor download progress use the `--progress-bar=raw` option. -This will print lines to stdout in the format `Progress CURRENT of TOTAL`, where -`CURRENT` and `TOTAL` are integers and the unit is bytes. -If the real total is unknown then `TOTAL` is set to `0`. Be aware that the -specific formatting of pip's outputs are not guaranteed to be the same in future versions. +To programmatically monitor download progress use the ``--progress-bar=raw`` option. +This will print lines to stdout in the format ``Progress CURRENT of TOTAL``, where +``CURRENT`` and ``TOTAL`` are integers and the unit is bytes. +If the real total is unknown then ``TOTAL`` is set to ``0``. Be aware that the +specific formatting of pip's outputs are *not* guaranteed to be the same in future versions. If you don't want to use pip's command line functionality, but are rather trying to implement code that works with Python packages, their metadata, or PyPI, then you should consider other, supported, packages that offer this type of ability. Some examples that you could consider include: -* `packaging` - Utilities to work with standard package metadata (versions, +* ``packaging`` - Utilities to work with standard package metadata (versions, requirements, etc.) -* `importlib.metadata` in the Python stdlib - Functions for querying what +* ``importlib.metadata`` in the Python stdlib - Functions for querying what packages the user has installed on their system. -* `distlib` - Packaging and distribution utilities (including functions for +* ``distlib`` - Packaging and distribution utilities (including functions for interacting with PyPI). .. _changes-to-the-pip-dependency-resolver-in-20-2-2020: @@ -1055,7 +1051,7 @@ The big change in this release is to the pip dependency resolver within pip. Computers need to know the right order to install pieces of software -("to install `x`, you need to install `y` first"). So, when Python +("to install ``x``, you need to install ``y`` first"). So, when Python programmers share software as packages, they have to precisely describe those installation prerequisites, and pip needs to navigate tricky situations where it's getting conflicting instructions. This new @@ -1064,19 +1060,19 @@ logic, and make pip easier for you to use and troubleshoot. The most significant changes to the resolver are: -* It will *reduce inconsistency*: it will *no longer install a +* It will **reduce inconsistency**: it will *no longer install a combination of packages that is mutually inconsistent*. In older versions of pip, it is possible for pip to install a package which does not satisfy the declared requirements of another installed package. For example, in pip 20.0, ``pip install "six<1.12" "virtualenv==20.0.2"`` does the wrong thing, “successfully” installing - `six==1.11`, even though `virtualenv==20.0.2` requires - `six>=1.12.0,<2` (`defined here + ``six==1.11``, even though ``virtualenv==20.0.2`` requires + ``six>=1.12.0,<2`` (`defined here `__). The new resolver, instead, outright rejects installing anything if it gets that input. -* It will be *stricter* - if you ask pip to install two packages with +* It will be **stricter** - if you ask pip to install two packages with incompatible requirements, it will refuse (rather than installing a broken combination, like it did in previous versions). @@ -1085,18 +1081,18 @@ incompatible or inconsistent requirements combinations, now's a good time to fix the underlying problem in the packages, because pip will be stricter from here on out. -This also means that, when you run a `pip install` command, pip only +This also means that, when you run a ``pip install`` command, pip only considers the packages you are installing in that command, and **may break already-installed packages**. It will not guarantee that your -environment will be consistent all the time. If you `pip install x` -and then `pip install y`, it's possible that the version of `y` +environment will be consistent all the time. If you ``pip install x`` +and then ``pip install y``, it's possible that the version of ``y`` you get will be different than it would be if you had run ``pip install x y`` in a single command. We are considering changing this -behavior (per :issue:7744) and would like your thoughts on what +behavior (per :issue:`7744`) and would like your thoughts on what pip's behavior should be; please answer `our survey on upgrades that create conflicts`_. -We are also changing our support for :ref:Constraints Files, +We are also changing our support for :ref:`Constraints Files`, editable installs, and related functionality. We did a fairly comprehensive overhaul and stripped constraints files down to being purely a way to specify global (version) limits for packages, and so @@ -1105,23 +1101,23 @@ errors. Specifically: * Constraints don't override the existing requirements; they simply constrain what versions are visible as input to the resolver (see - :issue:9020) -* Providing an editable requirement (`-e .`) does not cause pip to - ignore version specifiers or constraints (see :issue:8076), and if + :issue:`9020`) +* Providing an editable requirement (``-e .``) does not cause pip to + ignore version specifiers or constraints (see :issue:`8076`), and if you have a conflict between a pinned requirement and a local directory then pip will indicate that it cannot find a version - satisfying both (see :issue:8307) + satisfying both (see :issue:`8307`) * Hash-checking mode requires that all requirements are specified as a - `==` match on a version and may not work well in combination with - constraints (see :issue:9020 and :issue:8792) + ``==`` match on a version and may not work well in combination with + constraints (see :issue:`9020` and :issue:`8792`) * If necessary to satisfy constraints, pip will happily reinstall packages, upgrading or downgrading, without needing any additional - command-line options (see :issue:8115 and :doc:development/architecture/upgrade-options) -* Unnamed requirements are not allowed as constraints (see :issue:6628 and :issue:8210) -* Links are not allowed as constraints (see :issue:8253) -* Constraints cannot have extras (see :issue:6628) + command-line options (see :issue:`8115` and :doc:`development/architecture/upgrade-options`) +* Unnamed requirements are not allowed as constraints (see :issue:`6628` and :issue:`8210`) +* Links are not allowed as constraints (see :issue:`8253`) +* Constraints cannot have extras (see :issue:`6628`) -Per our :ref:Python 2 Support policy, pip 20.3 users who are using +Per our :ref:`Python 2 Support` policy, pip 20.3 users who are using Python 2 will use the legacy resolver by default. Python 2 users should upgrade to Python 3 as soon as possible, since in pip 21.0 in January 2021, pip dropped support for Python 2 altogether. @@ -1130,17 +1126,17 @@ January 2021, pip dropped support for Python 2 altogether. How to upgrade and migrate -------------------------- -1. *Install pip 20.3* with `python -m pip install --upgrade pip`. +1. **Install pip 20.3** with ``python -m pip install --upgrade pip``. -2. *Validate your current environment* by running `pip check`. This +2. **Validate your current environment** by running ``pip check``. This will report if you have any inconsistencies in your set of installed packages. Having a clean installation will make it much less likely that you will hit issues with the new resolver (and may address hidden problems in your current environment!). If you run - `pip check` and run into stuff you can’t figure out, please `ask + ``pip check`` and run into stuff you can’t figure out, please `ask for help in our issue tracker or chat `__. -3. *Test the new version of pip*. +3. **Test the new version of pip**. While we have tried to make sure that pip’s test suite covers as many cases as we can, we are very aware that there are people using @@ -1148,11 +1144,11 @@ How to upgrade and migrate not be able to cover all of those without your help. - If you use pip to install your software, try out the new resolver - and let us know if it works for you with `pip install`. Try: + and let us know if it works for you with ``pip install``. Try: - installing several packages simultaneously - - re-creating an environment using a `requirements.txt` file - - using `pip install --force-reinstall` to check whether + - re-creating an environment using a ``requirements.txt`` file + - using ``pip install --force-reinstall`` to check whether it does what you think it should - using constraints files - the "Setups to test with special attention" and "Examples to try" below @@ -1173,23 +1169,23 @@ How to upgrade and migrate deliver part of your functionality, please test your integration with pip 20.3. -4. *Troubleshoot and try these workarounds if necessary.* +4. **Troubleshoot and try these workarounds if necessary.** - If pip is taking longer to install packages, read :doc:`Dependency resolution backtracking ` for ways to reduce the time pip spends backtracking due to dependency conflicts. - If you don't want pip to actually resolve dependencies, use the - `--no-deps` option. This is useful when you have a set of package + ``--no-deps`` option. This is useful when you have a set of package versions that work together in reality, even though their metadata says that they conflict. For guidance on a long-term fix, read - :ref:Fixing conflicting dependencies. + :ref:`Fixing conflicting dependencies`. - If you run into resolution errors and need a workaround while you're fixing their root causes, you can choose the old resolver behavior using - the flag `--use-deprecated=legacy-resolver`. This will work until we + the flag ``--use-deprecated=legacy-resolver``. This will work until we release pip 21.0 (see - :ref:Deprecation timeline for 2020 resolver changes). + :ref:`Deprecation timeline for 2020 resolver changes`). -5. *Please report bugs* through the `resolver testing survey`_. +5. **Please report bugs** through the `resolver testing survey`_. Setups to test with special attention @@ -1199,15 +1195,15 @@ Setups to test with special attention * Installation workflows that involve multiple requirements files -* Requirements files that include hashes (:ref:hash-checking mode) - or pinned dependencies (perhaps as output from `pip-compile` within - `pip-tools`) +* Requirements files that include hashes (:ref:`hash-checking mode`) + or pinned dependencies (perhaps as output from ``pip-compile`` within + ``pip-tools``) -* Using :ref:Constraints Files +* Using :ref:`Constraints Files` * Continuous integration/continuous deployment setups -* Installing from any kind of version control systems (i.e., Git, Subversion, Mercurial, or CVS), per :doc:topics/vcs-support +* Installing from any kind of version control systems (i.e., Git, Subversion, Mercurial, or CVS), per :doc:`topics/vcs-support` * Installing from source code held in local directories @@ -1217,21 +1213,21 @@ Examples to try Install: * `tensorflow`_ -* `hacking` -* `pycodestyle` -* `pandas` -* `tablib` -* `elasticsearch` and `requests` together -* `six` and `cherrypy` together -* `pip install flake8-import-order==0.17.1 flake8==3.5.0 --use-feature=2020-resolver` -* `pip install tornado==5.0 sprockets.http==1.5.0 --use-feature=2020-resolver` +* ``hacking`` +* ``pycodestyle`` +* ``pandas`` +* ``tablib`` +* ``elasticsearch`` and ``requests`` together +* ``six`` and ``cherrypy`` together +* ``pip install flake8-import-order==0.17.1 flake8==3.5.0 --use-feature=2020-resolver`` +* ``pip install tornado==5.0 sprockets.http==1.5.0 --use-feature=2020-resolver`` Try: -* `pip install` -* `pip uninstall` -* `pip check` -* `pip cache` +* ``pip install`` +* ``pip uninstall`` +* ``pip check`` +* ``pip cache`` Tell us about @@ -1261,32 +1257,32 @@ Deprecation timeline -------------------- We plan for the resolver changeover to proceed as follows, using -:ref:Feature Flags and following our :ref:Release Cadence: +:ref:`Feature Flags` and following our :ref:`Release Cadence`: * pip 20.1: an alpha version of the new resolver was available, opt-in, using the optional flag - `--unstable-feature=resolver`. pip defaulted to legacy + ``--unstable-feature=resolver``. pip defaulted to legacy behavior. * pip 20.2: a beta of the new resolver was available, opt-in, using - the flag `--use-feature=2020-resolver`. pip defaulted to legacy + the flag ``--use-feature=2020-resolver``. pip defaulted to legacy behavior. Users of pip 20.2 who want pip to default to using the new resolver can run ``pip config set global.use-feature 2020-resolver`` (for more on that and the alternate - `PIP_USE_FEATURE` environment variable option, see `issue + ``PIP_USE_FEATURE`` environment variable option, see `issue 8661`_). * pip 20.3: pip defaults to the new resolver in Python 3 environments, but a user can opt-out and choose the old resolver behavior, - using the flag `--use-deprecated=legacy-resolver`. In Python 2 + using the flag ``--use-deprecated=legacy-resolver``. In Python 2 environments, pip defaults to the old resolver, and the new one is - available using the flag `--use-feature=2020-resolver`. + available using the flag ``--use-feature=2020-resolver``. * pip 21.0: pip uses new resolver by default, and the old resolver is no longer supported. It will be removed after a currently undecided amount of time, as the removal is dependent on pip's volunteer maintainers' availability. Python 2 support is removed per our - :ref:Python 2 Support policy. + :ref:`Python 2 Support` policy. Since this work will not change user-visible behavior described in the pip documentation, this change is not covered by the :ref:`Deprecation @@ -1295,7 +1291,7 @@ Policy`. .. attention:: The legacy resolver is deprecated and unsupported. New features, such - as :doc:reference/installation-report, will not work with the + as :doc:`reference/installation-report`, will not work with the legacy resolver and this resolver will be removed in a future release. @@ -1306,7 +1302,7 @@ As discussed in `our announcement on the PSF blog`_, the pip team are in the process of developing a new "dependency resolver" (the part of pip that works out what to install based on your requirements). -We're tracking our rollout in :issue:6536 and you can watch for +We're tracking our rollout in :issue:`6536` and you can watch for announcements on the `low-traffic packaging announcements list`_ and `the official Python blog`_. @@ -1324,4 +1320,4 @@ announcements on the `low-traffic packaging announcements list`_ and .. _`0-using-system-trust-stores-for-verifying-https`: .. rubric:: Using system trust stores for verifying HTTPS -This is now covered in :doc:topics/https-certificates. \ No newline at end of file +This is now covered in :doc:`topics/https-certificates`. \ No newline at end of file From 6e0fe0ca577e395417659e2753934498f6350cc2 Mon Sep 17 00:00:00 2001 From: Mennaalazaz <162923696+Mennaalazaz@users.noreply.github.com> Date: Thu, 11 Dec 2025 13:29:52 +0200 Subject: [PATCH 3/3] Add beginner example in Running pip section --- docs/html/user_guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/html/user_guide.rst b/docs/html/user_guide.rst index f74061ef9ce..61200522889 100644 --- a/docs/html/user_guide.rst +++ b/docs/html/user_guide.rst @@ -56,7 +56,7 @@ to your system, which can be run from the command prompt as follows: py -m pip install requests This installs the `requests` library using the latest Python interpreter available on your system. - + Installing Packages ===================