Merge pull request #808 from scop/python-m-pip

di · web-flow · commit 485adbecf9c1 · 2021-02-08T13:50:54.000-06:00
Use `python -m pip` instead of just `pip` in pip invocations
diff --git a/source/contribute.rst b/source/contribute.rst
@@ -79,7 +79,7 @@ need:
 1. `Nox <https://nox.readthedocs.io/en/latest/>`_. You can install or upgrade
    nox using ``pip``::
 
-      pip install --user nox
+      python -m pip install --user nox
 
 2. Python 3.6. Our build scripts are designed to work with Python 3.6 only.
    See the `Hitchhiker's Guide to Python installation instructions`_ to install
diff --git a/source/discussions/install-requires-vs-requirements.rst b/source/discussions/install-requires-vs-requirements.rst
@@ -83,7 +83,7 @@ packages. [1]_
 
 Whereas ``install_requires`` metadata is automatically analyzed by pip during an
 install, requirements files are not, and only are used when a user specifically
-installs them using ``pip install -r``.
+installs them using ``python -m pip install -r``.
 
 ----
 
diff --git a/source/discussions/pip-vs-easy-install.rst b/source/discussions/pip-vs-easy-install.rst
@@ -27,13 +27,13 @@ Here's a breakdown of the important differences between pip and easy_install now
 |Installs from :term:`Wheels   |Yes                                   |No                             |
 |<Wheel>`                      |                                      |                               |
 +------------------------------+--------------------------------------+-------------------------------+
-|Uninstall Packages            |Yes (``pip uninstall``)               |No                             |
+|Uninstall Packages            |Yes (``python -m pip uninstall``)     |No                             |
 +------------------------------+--------------------------------------+-------------------------------+
 |Dependency Overrides          |Yes (:ref:`Requirements Files         |No                             |
 |                              |<pip:Requirements Files>`)            |                               |
 +------------------------------+--------------------------------------+-------------------------------+
-|List Installed Packages       |Yes (``pip list`` and ``pip           |No                             |
-|                              |freeze``)                             |                               |
+|List Installed Packages       |Yes (``python -m pip list`` and       |No                             |
+|                              |``python -m pip freeze``)             |                               |
 +------------------------------+--------------------------------------+-------------------------------+
 |:pep:`438`                    |Yes                                   |No                             |
 |Support                       |                                      |                               |
diff --git a/source/guides/analyzing-pypi-package-downloads.rst b/source/guides/analyzing-pypi-package-downloads.rst
@@ -274,7 +274,7 @@ Install `pypinfo`_ using pip.
 
 ::
 
-    pip install pypinfo
+    python -m pip install pypinfo
 
 Usage:
 
diff --git a/source/guides/distributing-packages-using-setuptools.rst b/source/guides/distributing-packages-using-setuptools.rst
@@ -32,7 +32,7 @@ Requirements for packaging and distributing
 
    ::
 
-    pip install twine
+    python -m pip install twine
 
    You'll need this to upload your project :term:`distributions <Distribution
    Package>` to :term:`PyPI <Python Package Index (PyPI)>` (see :ref:`below
@@ -667,7 +667,7 @@ Assuming you're in the root of your project directory, then run:
 
 ::
 
- pip install -e .
+ python -m pip install -e .
 
 
 Although somewhat cryptic, ``-e`` is short for ``--editable``, and ``.`` refers
@@ -699,7 +699,7 @@ see the :ref:`VCS Support <pip:VCS Support>` section of the pip docs.
 
 Lastly, if you don't want to install any dependencies at all, you can run::
 
-   pip install -e . --no-deps
+   python -m pip install -e . --no-deps
 
 
 For more information, see the `Development Mode
@@ -759,7 +759,7 @@ Before you can build wheels for your project, you'll need to install the
 
 .. code-block:: text
 
-  pip install wheel
+  python -m pip install wheel
 
 
 .. _`Universal Wheels`:
diff --git a/source/guides/dropping-older-python-versions.rst b/source/guides/dropping-older-python-versions.rst
@@ -32,7 +32,7 @@ Ensure that before you generate source distributions or binary distributions, yo
 
 Steps::
 
-   pip install --upgrade setuptools twine
+   python -m pip install --upgrade setuptools twine
 
 `setuptools` version should be above 24.0.0.
 
diff --git a/source/guides/hosting-your-own-index.rst b/source/guides/hosting-your-own-index.rst
@@ -14,7 +14,7 @@ In either case, since you'll be hosting a repository that is likely not in
 your user's default repositories, you should instruct them in your project's
 description to configure their installer appropriately. For example with pip::
 
-    pip install --extra-index-url https://python.example.com/ foobar
+    python -m pip install --extra-index-url https://python.example.com/ foobar
 
 In addition, it is **highly** recommended that you serve your repository with
 valid HTTPS. At this time, the security of your user's installations depends on
diff --git a/source/guides/index-mirrors-and-caches.rst b/source/guides/index-mirrors-and-caches.rst
@@ -34,11 +34,11 @@ cached copies of :term:`packages <Distribution Package>`:
    by downloading all the requirements for a project and then pointing pip at
    those downloaded files instead of going to PyPI.
 2. A variation on the above which pre-builds the installation files for
-   the requirements using `pip wheel
+   the requirements using `python -m pip wheel
    <https://pip.readthedocs.io/en/latest/reference/pip_wheel.html>`_::
 
-    $ pip wheel --wheel-dir=/tmp/wheelhouse SomeProject
-    $ pip install --no-index --find-links=/tmp/wheelhouse SomeProject
+    $ python -m pip wheel --wheel-dir=/tmp/wheelhouse SomeProject
+    $ python -m pip install --no-index --find-links=/tmp/wheelhouse SomeProject
 
 
 Caching with devpi
diff --git a/source/guides/installing-stand-alone-command-line-tools.rst b/source/guides/installing-stand-alone-command-line-tools.rst
@@ -87,8 +87,8 @@ To upgrade or uninstall the package
 
 ::
 
-  $ pip install -U pipx
-  $ pip uninstall pipx
+  $ python3 -m pip install -U pipx
+  $ python3 -m pip uninstall pipx
 
 ``pipx`` also allows you to install and run the latest version of a cli tool
 in a temporary, ephemeral environment.
diff --git a/source/guides/installing-using-pip-and-virtual-environments.rst b/source/guides/installing-using-pip-and-virtual-environments.rst
@@ -188,7 +188,7 @@ Now that you're in your virtual environment you can install packages. Let's inst
 
 .. code-block:: bash
 
-    pip install requests
+    python3 -m pip install requests
 
 pip should download requests and all of its dependencies and install them:
 
@@ -219,19 +219,19 @@ a specific version of ``requests``:
 
 .. code-block:: bash
 
-    pip install requests==2.18.4
+    python3 -m pip install requests==2.18.4
 
 To install the latest ``2.x`` release of requests:
 
 .. code-block:: bash
 
-    pip install requests>=2.0.0,<3.0.0
+    python3 -m pip install requests>=2.0.0,<3.0.0
 
 To install pre-release versions of packages, use the ``--pre`` flag:
 
 .. code-block:: bash
 
-    pip install --pre requests
+    python3 -m pip install --pre requests
 
 
 Installing extras
@@ -242,7 +242,7 @@ specifying the extra in brackets:
 
 .. code-block:: bash
 
-    pip install requests[security]
+    python3 -m pip install requests[security]
 
 .. _extras:
     https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies
@@ -256,15 +256,15 @@ pip can install a package directly from source, for example:
 .. code-block:: bash
 
     cd google-auth
-    pip install .
+    python3 -m pip install .
 
 Additionally, pip can install packages from source in `development mode`_,
 meaning that changes to the source directory will immediately affect the
 installed package without needing to re-install:
 
 .. code-block:: bash
 
-    pip install --editable .
+    python3 -m pip install --editable .
 
 
 .. _development mode:
@@ -293,15 +293,15 @@ wheel, or tar file) you can install it directly with pip:
 
 .. code-block:: bash
 
-    pip install requests-2.18.4.tar.gz
+    python3 -m pip install requests-2.18.4.tar.gz
 
 If you have a directory containing archives of multiple packages, you can tell
 pip to look for packages there and not to use the
 :term:`Python Package Index (PyPI)` at all:
 
 .. code-block:: bash
 
-    pip install --no-index --find-links=/local/dir/ requests
+    python3 -m pip install --no-index --find-links=/local/dir/ requests
 
 This is useful if you are installing packages on a system with limited
 connectivity or if you want to strictly control the origin of distribution
@@ -316,15 +316,15 @@ If you want to download packages from a different index than the
 
 .. code-block:: bash
 
-    pip install --index-url http://index.example.com/simple/ SomeProject
+    python3 -m pip install --index-url http://index.example.com/simple/ SomeProject
 
 If you want to allow packages from both the :term:`Python Package Index (PyPI)`
 and a separate index, you can use the ``--extra-index-url`` flag instead:
 
 
 .. code-block:: bash
 
-    pip install --extra-index-url http://index.example.com/simple/ SomeProject
+    python3 -m pip install --extra-index-url http://index.example.com/simple/ SomeProject
 
 
 Upgrading packages
@@ -335,7 +335,7 @@ install the latest version of ``requests`` and all of its dependencies:
 
 .. code-block:: bash
 
-    pip install --upgrade requests
+    python3 -m pip install --upgrade requests
 
 
 Using requirements files
@@ -354,7 +354,7 @@ And tell pip to install all of the packages in this file using the ``-r`` flag:
 
 .. code-block:: bash
 
-    pip install -r requirements.txt
+    python3 -m pip install -r requirements.txt
 
 
 Freezing dependencies
@@ -365,7 +365,7 @@ Pip can export a list of all installed packages and their versions using the
 
 .. code-block:: bash
 
-    pip freeze
+    python3 -m pip freeze
 
 Which will output a list of package specifiers such as:
 
diff --git a/source/guides/making-a-pypi-friendly-readme.rst b/source/guides/making-a-pypi-friendly-readme.rst
@@ -99,7 +99,7 @@ You can check your README for markup errors before uploading as follows:
 1. Install the latest version of `twine <https://github.com/pypa/twine>`_;
    version 1.12.0 or higher is required::
 
-        pip install --upgrade twine
+        python3 -m pip install --upgrade twine
 
 2. Build the sdist and wheel for your project as described under
    :ref:`Packaging Your Project`.
diff --git a/source/guides/supporting-windows-using-appveyor.rst b/source/guides/supporting-windows-using-appveyor.rst
@@ -29,7 +29,7 @@ extensions.
 
 Windows users typically do not have access to a C compiler, and therefore are
 reliant on projects that use C extensions distributing binary wheels on PyPI in
-order for the distribution to be installable via ``pip install <dist>``. By
+order for the distribution to be installable via ``python -m pip install <dist>``. By
 using Appveyor as a build service (even if not using it for testing) it is
 possible for projects without a dedicated Windows environment to provide
 Windows-targeted binaries.
diff --git a/source/guides/using-testpypi.rst b/source/guides/using-testpypi.rst
@@ -43,15 +43,15 @@ specifying the ``--index-url`` flag
 
 .. code::
 
-    $ pip install --index-url https://test.pypi.org/simple/ your-package
+    $ python -m pip install --index-url https://test.pypi.org/simple/ your-package
 
 If you want to allow pip to also pull other packages from PyPI you can
 specify ``--extra-index-url`` to point to PyPI. This is useful when the package
 you're testing has dependencies:
 
 .. code::
 
-    pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple your-package
+    python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple your-package
 
 Setting up TestPyPI in :file:`.pypirc`
 --------------------------------------
diff --git a/source/overview.rst b/source/overview.rst
@@ -424,7 +424,7 @@ used as a primitive in `the dh-virtualenv tool
 `osnap <https://github.com/jamesabel/osnap>`_, both of which wrap
 virtualenvs in a self-contained way.
 
-For production deployments, do not rely on running ``pip install``
+For production deployments, do not rely on running ``python -m pip install``
 from the Internet into a virtualenv, as one might do in a development
 environment. The overview above is full of much better solutions.
 
diff --git a/source/tutorials/creating-documentation.rst b/source/tutorials/creating-documentation.rst
@@ -15,7 +15,7 @@ Use ``pip`` to install Sphinx:
 
 .. code-block:: bash
 
-	pip install -U sphinx
+	python -m pip install -U sphinx
 
 For other installation methods, see this `installation guide`_ by Sphinx.
 
diff --git a/source/tutorials/installing-packages.rst b/source/tutorials/installing-packages.rst
diff --git a/source/tutorials/managing-dependencies.rst b/source/tutorials/managing-dependencies.rst
diff --git a/source/tutorials/packaging-projects.rst b/source/tutorials/packaging-projects.rst
