diff --git a/docs/html/conf.py b/docs/html/conf.py index 2ef2647ce72..a88ac33e2e4 100644 --- a/docs/html/conf.py +++ b/docs/html/conf.py @@ -30,7 +30,12 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. # extensions = ['sphinx.ext.autodoc'] -extensions = ['sphinx.ext.extlinks', 'pip_sphinxext', 'sphinx.ext.intersphinx'] +extensions = [ + 'sphinx.ext.extlinks', + 'pip_sphinxext', + 'sphinx.ext.intersphinx', + 'sphinx_tabs.tabs', +] # intersphinx intersphinx_cache_limit = 0 @@ -130,6 +135,9 @@ 'pypi': ('https://pypi.org/project/%s/', ''), } +# Turn off sphinx build warnings because of sphinx tabs during man pages build +sphinx_tabs_nowarn = True + # -- Options for HTML output -------------------------------------------------- # The theme to use for HTML and HTML Help pages. Major themes that come with diff --git a/docs/html/development/getting-started.rst b/docs/html/development/getting-started.rst index 326543202f6..1bc4a551621 100644 --- a/docs/html/development/getting-started.rst +++ b/docs/html/development/getting-started.rst @@ -38,13 +38,25 @@ To run the pip executable from your source tree during development, install pip locally using editable installation (inside a virtualenv). You can then invoke your local source tree pip normally. -.. code-block:: console +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + virtualenv venv # You can also use "python -m venv venv" from python3.3+ + source venv/bin/activate + python -m pip install -e . + python -m pip --version + + .. group-tab:: Windows - $ virtualenv venv # You can also use "python -m venv venv" from python3.3+ - $ source venv/bin/activate - $ python -m pip install -e . - $ python -m pip --version + .. code-block:: shell + virtualenv venv # You can also use "py -m venv venv" from python3.3+ + venv\Scripts\activate + py -m pip install -e . + py -m pip --version Running Tests ============= diff --git a/docs/html/installing.rst b/docs/html/installing.rst index 0a263ac4137..5379c1da0e0 100644 --- a/docs/html/installing.rst +++ b/docs/html/installing.rst @@ -26,9 +26,21 @@ this link: `get-pip.py curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py Then run the following command in the folder where you -have downloaded ``get-pip.py``:: +have downloaded ``get-pip.py``: - python get-pip.py +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python get-pip.py + + .. group-tab:: Windows + + .. code-block:: shell + + py get-pip.py .. warning:: @@ -67,23 +79,70 @@ get-pip.py options install Options>` and the :ref:`general options `. Below are some examples: -Install from local copies of pip and setuptools:: +Install from local copies of pip and setuptools: + +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python get-pip.py --no-index --find-links=/local/copies + + .. group-tab:: Windows + + .. code-block:: shell + + py get-pip.py --no-index --find-links=/local/copies + +Install to the user site [3]_: + +.. tabs:: + + .. group-tab:: Unix/macOS - python get-pip.py --no-index --find-links=/local/copies + .. code-block:: shell -Install to the user site [3]_:: + python get-pip.py --user - python get-pip.py --user + .. group-tab:: Windows -Install behind a proxy:: + .. code-block:: shell - python get-pip.py --proxy="http://[user:passwd@]proxy.server:port" + py get-pip.py --user + +Install behind a proxy: + +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python get-pip.py --proxy="http://[user:passwd@]proxy.server:port" + + .. group-tab:: Windows + + .. code-block:: shell + + py get-pip.py --proxy="http://[user:passwd@]proxy.server:port" ``get-pip.py`` can also be used to install a specified combination of ``pip``, -``setuptools``, and ``wheel`` using the same requirements syntax as pip:: +``setuptools``, and ``wheel`` using the same requirements syntax as pip: - python get-pip.py pip==9.0.2 wheel==0.30.0 setuptools==28.8.0 +.. tabs:: + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python get-pip.py pip==9.0.2 wheel==0.30.0 setuptools==28.8.0 + + .. group-tab:: Windows + + .. code-block:: shell + + py get-pip.py pip==9.0.2 wheel==0.30.0 setuptools==28.8.0 Using Linux Package Managers ============================ @@ -97,14 +156,19 @@ the `Python Packaging User Guide Upgrading pip ============= -On Linux or macOS:: +.. tabs:: + + .. group-tab:: Unix/macOS - pip install -U pip + .. code-block:: shell + python -m pip install -U pip -On Windows [4]_:: + .. group-tab:: Windows - python -m pip install -U pip + .. code-block:: shell + + py -m pip install -U pip .. _compatibility-requirements: @@ -134,5 +198,3 @@ pip works on Unix/Linux, macOS, and Windows. ``--user`` installs for pip itself, should not be considered to be fully tested or endorsed. For discussion, see `Issue 1668 `_. - -.. [4] https://github.com/pypa/pip/issues/1299 diff --git a/docs/html/quickstart.rst b/docs/html/quickstart.rst index c2250399c6a..9591e1127f5 100644 --- a/docs/html/quickstart.rst +++ b/docs/html/quickstart.rst @@ -6,62 +6,145 @@ First, :doc:`install pip `. Install a package from `PyPI`_: -:: +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: console + + $ python -m pip install SomePackage + [...] + Successfully installed SomePackage + + .. group-tab:: Windows + + .. code-block:: console + + C:\> py -m pip install SomePackage + [...] + Successfully installed SomePackage - $ pip install SomePackage - [...] - Successfully installed SomePackage Install a package that's already been downloaded from `PyPI`_ or obtained from elsewhere. This is useful if the target machine does not have a network connection: -:: +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: console + + $ python -m pip install SomePackage-1.0-py2.py3-none-any.whl + [...] + Successfully installed SomePackage + + .. group-tab:: Windows + + .. code-block:: console + + C:\> py -m pip install SomePackage-1.0-py2.py3-none-any.whl + [...] + Successfully installed SomePackage - $ pip install SomePackage-1.0-py2.py3-none-any.whl - [...] - Successfully installed SomePackage Show what files were installed: -:: +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: console + + $ python -m pip show --files SomePackage + Name: SomePackage + Version: 1.0 + Location: /my/env/lib/pythonx.x/site-packages + Files: + ../somepackage/__init__.py + [...] + + .. group-tab:: Windows - $ pip show --files SomePackage - Name: SomePackage - Version: 1.0 - Location: /my/env/lib/pythonx.x/site-packages - Files: - ../somepackage/__init__.py - [...] + .. code-block:: console + + C:\> py -m pip show --files SomePackage + Name: SomePackage + Version: 1.0 + Location: /my/env/lib/pythonx.x/site-packages + Files: + ../somepackage/__init__.py + [...] List what packages are outdated: -:: +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: console + + $ python -m pip list --outdated + SomePackage (Current: 1.0 Latest: 2.0) - $ pip list --outdated - SomePackage (Current: 1.0 Latest: 2.0) + .. group-tab:: Windows + + .. code-block:: console + + C:\> py -m pip list --outdated + SomePackage (Current: 1.0 Latest: 2.0) Upgrade a package: -:: +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: console - $ pip install --upgrade SomePackage - [...] - Found existing installation: SomePackage 1.0 - Uninstalling SomePackage: - Successfully uninstalled SomePackage - Running setup.py install for SomePackage - Successfully installed SomePackage + $ python -m pip install --upgrade SomePackage + [...] + Found existing installation: SomePackage 1.0 + Uninstalling SomePackage: + Successfully uninstalled SomePackage + Running setup.py install for SomePackage + Successfully installed SomePackage + + .. group-tab:: Windows + + .. code-block:: console + + C:\> py -m pip install --upgrade SomePackage + [...] + Found existing installation: SomePackage 1.0 + Uninstalling SomePackage: + Successfully uninstalled SomePackage + Running setup.py install for SomePackage + Successfully installed SomePackage Uninstall a package: -:: +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: console + + $ python -m pip uninstall SomePackage + Uninstalling SomePackage: + /my/env/lib/pythonx.x/site-packages/somepackage + Proceed (y/n)? y + Successfully uninstalled SomePackage + + .. group-tab:: Windows + + .. code-block:: console - $ pip uninstall SomePackage - Uninstalling SomePackage: - /my/env/lib/pythonx.x/site-packages/somepackage - Proceed (y/n)? y - Successfully uninstalled SomePackage + C:\> py -m pip uninstall SomePackage + Uninstalling SomePackage: + /my/env/lib/pythonx.x/site-packages/somepackage + Proceed (y/n)? y + Successfully uninstalled SomePackage .. _PyPI: https://pypi.org/ diff --git a/docs/html/reference/pip.rst b/docs/html/reference/pip.rst index 9c218f3557d..9fd42c676a9 100644 --- a/docs/html/reference/pip.rst +++ b/docs/html/reference/pip.rst @@ -7,10 +7,19 @@ pip Usage ***** -:: +.. tabs:: - pip [options] + .. group-tab:: Unix/macOS + .. code-block:: shell + + python -m pip [options] + + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip [options] Description *********** @@ -221,9 +230,21 @@ Build Options The ``--global-option`` and ``--build-option`` arguments to the ``pip install`` and ``pip wheel`` inject additional arguments into the ``setup.py`` command (``--build-option`` is only available in ``pip wheel``). These arguments are -included in the command as follows:: +included in the command as follows: + +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: console + + python setup.py BUILD COMMAND + + .. group-tab:: Windows + + .. code-block:: shell - python setup.py BUILD COMMAND + py setup.py BUILD COMMAND The options are passed unmodified, and presently offer direct access to the distutils command line. Use of ``--global-option`` and ``--build-option`` diff --git a/docs/html/reference/pip_cache.rst b/docs/html/reference/pip_cache.rst index 8ad99f65cba..35e0dfcadac 100644 --- a/docs/html/reference/pip_cache.rst +++ b/docs/html/reference/pip_cache.rst @@ -9,7 +9,15 @@ pip cache Usage ***** -.. pip-command-usage:: cache +.. tabs:: + + .. group-tab:: Unix/macOS + + .. pip-command-usage:: cache "python -m pip" + + .. group-tab:: Windows + + .. pip-command-usage:: cache "py -m pip" Description *********** diff --git a/docs/html/reference/pip_check.rst b/docs/html/reference/pip_check.rst index a12d5b3ec78..d3bb457e12c 100644 --- a/docs/html/reference/pip_check.rst +++ b/docs/html/reference/pip_check.rst @@ -10,7 +10,15 @@ pip check Usage ===== -.. pip-command-usage:: check +.. tabs:: + + .. group-tab:: Unix/macOS + + .. pip-command-usage:: check "python -m pip" + + .. group-tab:: Windows + + .. pip-command-usage:: check "py -m pip" Description @@ -24,27 +32,66 @@ Examples #. If all dependencies are compatible: - :: + .. tabs:: + + .. group-tab:: Unix/macOS - $ pip check - No broken requirements found. - $ echo $? - 0 + .. code-block:: console + + $ python -m pip check + No broken requirements found. + $ echo $? + 0 + + .. group-tab:: Windows + + .. code-block:: console + + C:\> py -m pip check + No broken requirements found. + C:\> echo %errorlevel% + 0 #. If a package is missing: - :: + .. tabs:: + + .. group-tab:: Unix/macOS - $ pip check - pyramid 1.5.2 requires WebOb, which is not installed. - $ echo $? - 1 + .. code-block:: console + + $ python -m pip check + pyramid 1.5.2 requires WebOb, which is not installed. + $ echo $? + 1 + + .. group-tab:: Windows + + .. code-block:: console + + C:\> py -m pip check + pyramid 1.5.2 requires WebOb, which is not installed. + C:\> echo %errorlevel% + 1 #. If a package has the wrong version: - :: + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: console + + $ python -m pip check + pyramid 1.5.2 has requirement WebOb>=1.3.1, but you have WebOb 0.8. + $ echo $? + 1 + + .. group-tab:: Windows + + .. code-block:: console - $ pip check - pyramid 1.5.2 has requirement WebOb>=1.3.1, but you have WebOb 0.8. - $ echo $? - 1 + C:\> py -m pip check + pyramid 1.5.2 has requirement WebOb>=1.3.1, but you have WebOb 0.8. + C:\> echo %errorlevel% + 1 diff --git a/docs/html/reference/pip_config.rst b/docs/html/reference/pip_config.rst index 70d9406c562..d9bf0afc8f5 100644 --- a/docs/html/reference/pip_config.rst +++ b/docs/html/reference/pip_config.rst @@ -11,7 +11,15 @@ pip config Usage ===== -.. pip-command-usage:: config +.. tabs:: + + .. group-tab:: Unix/macOS + + .. pip-command-usage:: config "python -m pip" + + .. group-tab:: Windows + + .. pip-command-usage:: config "py -m pip" Description diff --git a/docs/html/reference/pip_debug.rst b/docs/html/reference/pip_debug.rst index da147bcf2fa..2ef98228aa8 100644 --- a/docs/html/reference/pip_debug.rst +++ b/docs/html/reference/pip_debug.rst @@ -10,7 +10,15 @@ pip debug Usage ===== -.. pip-command-usage:: debug +.. tabs:: + + .. group-tab:: Unix/macOS + + .. pip-command-usage:: debug "python -m pip" + + .. group-tab:: Windows + + .. pip-command-usage:: debug "py -m pip" .. warning:: diff --git a/docs/html/reference/pip_download.rst b/docs/html/reference/pip_download.rst index b74b1d24038..7983bb95b04 100644 --- a/docs/html/reference/pip_download.rst +++ b/docs/html/reference/pip_download.rst @@ -11,7 +11,15 @@ pip download Usage ===== -.. pip-command-usage:: download +.. tabs:: + + .. group-tab:: Unix/macOS + + .. pip-command-usage:: download "python -m pip" + + .. group-tab:: Windows + + .. pip-command-usage:: download "py -m pip" Description @@ -56,64 +64,148 @@ Examples #. Download a package and all of its dependencies - :: + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python -m pip download SomePackage + python -m pip download -d . SomePackage # equivalent to above + python -m pip download --no-index --find-links=/tmp/wheelhouse -d /tmp/otherwheelhouse SomePackage + + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip download SomePackage + py -m pip download -d . SomePackage # equivalent to above + py -m pip download --no-index --find-links=/tmp/wheelhouse -d /tmp/otherwheelhouse SomePackage - $ pip download SomePackage - $ pip download -d . SomePackage # equivalent to above - $ pip download --no-index --find-links=/tmp/wheelhouse -d /tmp/otherwheelhouse SomePackage #. Download a package and all of its dependencies with OSX specific interpreter constraints. - This forces OSX 10.10 or lower compatibility. Since OSX deps are forward compatible, - this will also match ``macosx-10_9_x86_64``, ``macosx-10_8_x86_64``, ``macosx-10_8_intel``, - etc. - It will also match deps with platform ``any``. Also force the interpreter version to ``27`` - (or more generic, i.e. ``2``) and implementation to ``cp`` (or more generic, i.e. ``py``). + This forces OSX 10.10 or lower compatibility. Since OSX deps are forward compatible, + this will also match ``macosx-10_9_x86_64``, ``macosx-10_8_x86_64``, ``macosx-10_8_intel``, + etc. + It will also match deps with platform ``any``. Also force the interpreter version to ``27`` + (or more generic, i.e. ``2``) and implementation to ``cp`` (or more generic, i.e. ``py``). + + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python -m pip download \ + --only-binary=:all: \ + --platform macosx-10_10_x86_64 \ + --python-version 27 \ + --implementation cp \ + SomePackage - :: + .. group-tab:: Windows - $ pip download \ - --only-binary=:all: \ - --platform macosx-10_10_x86_64 \ - --python-version 27 \ - --implementation cp \ - SomePackage + .. code-block:: shell + + py -m pip download ^ + --only-binary=:all: ^ + --platform macosx-10_10_x86_64 ^ + --python-version 27 ^ + --implementation cp ^ + SomePackage #. Download a package and its dependencies with linux specific constraints. - Force the interpreter to be any minor version of py3k, and only accept - ``cp34m`` or ``none`` as the abi. + Force the interpreter to be any minor version of py3k, and only accept + ``cp34m`` or ``none`` as the abi. + + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell - :: + python -m pip download \ + --only-binary=:all: \ + --platform linux_x86_64 \ + --python-version 3 \ + --implementation cp \ + --abi cp34m \ + SomePackage - $ pip download \ - --only-binary=:all: \ - --platform linux_x86_64 \ - --python-version 3 \ - --implementation cp \ - --abi cp34m \ - SomePackage + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip download ^ + --only-binary=:all: ^ + --platform linux_x86_64 ^ + --python-version 3 ^ + --implementation cp ^ + --abi cp34m ^ + SomePackage #. Force platform, implementation, and abi agnostic deps. - :: + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python -m pip download \ + --only-binary=:all: \ + --platform any \ + --python-version 3 \ + --implementation py \ + --abi none \ + SomePackage - $ pip download \ - --only-binary=:all: \ - --platform any \ - --python-version 3 \ - --implementation py \ - --abi none \ - SomePackage + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip download ^ + --only-binary=:all: ^ + --platform any ^ + --python-version 3 ^ + --implementation py ^ + --abi none ^ + SomePackage #. Even when overconstrained, this will still correctly fetch the pip universal wheel. - :: - - $ pip download \ - --only-binary=:all: \ - --platform linux_x86_64 \ - --python-version 33 \ - --implementation cp \ - --abi cp34m \ - pip>=8 - $ ls pip-8.1.1-py2.py3-none-any.whl - pip-8.1.1-py2.py3-none-any.whl + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: console + + $ python -m pip download \ + --only-binary=:all: \ + --platform linux_x86_64 \ + --python-version 33 \ + --implementation cp \ + --abi cp34m \ + pip>=8 + + .. code-block:: console + + $ ls pip-8.1.1-py2.py3-none-any.whl + pip-8.1.1-py2.py3-none-any.whl + + .. group-tab:: Windows + + .. code-block:: console + + C:\> py -m pip download ^ + --only-binary=:all: ^ + --platform linux_x86_64 ^ + --python-version 33 ^ + --implementation cp ^ + --abi cp34m ^ + pip>=8 + + .. code-block:: console + + C:\> dir pip-8.1.1-py2.py3-none-any.whl + pip-8.1.1-py2.py3-none-any.whl diff --git a/docs/html/reference/pip_freeze.rst b/docs/html/reference/pip_freeze.rst index 31efd571b5f..d4ed00bfb3e 100644 --- a/docs/html/reference/pip_freeze.rst +++ b/docs/html/reference/pip_freeze.rst @@ -11,7 +11,15 @@ pip freeze Usage ===== -.. pip-command-usage:: freeze +.. tabs:: + + .. group-tab:: Unix/macOS + + .. pip-command-usage:: freeze "python -m pip" + + .. group-tab:: Windows + + .. pip-command-usage:: freeze "py -m pip" Description @@ -31,19 +39,45 @@ Examples #. Generate output suitable for a requirements file. - :: + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: console + + $ python -m pip freeze + docutils==0.11 + Jinja2==2.7.2 + MarkupSafe==0.19 + Pygments==1.6 + Sphinx==1.2.2 - $ pip freeze - docutils==0.11 - Jinja2==2.7.2 - MarkupSafe==0.19 - Pygments==1.6 - Sphinx==1.2.2 + .. group-tab:: Windows + + .. code-block:: console + + C:\> py -m pip freeze + docutils==0.11 + Jinja2==2.7.2 + MarkupSafe==0.19 + Pygments==1.6 + Sphinx==1.2.2 #. Generate a requirements file and then install from it in another environment. - :: + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + env1/bin/python -m pip freeze > requirements.txt + env2/bin/python -m pip install -r requirements.txt + + .. group-tab:: Windows + + .. code-block:: shell - $ env1/bin/pip freeze > requirements.txt - $ env2/bin/pip install -r requirements.txt + env1\bin\python -m pip freeze > requirements.txt + env2\bin\python -m pip install -r requirements.txt diff --git a/docs/html/reference/pip_hash.rst b/docs/html/reference/pip_hash.rst index dbf1f3e94f8..71e1cf4be6c 100644 --- a/docs/html/reference/pip_hash.rst +++ b/docs/html/reference/pip_hash.rst @@ -10,7 +10,15 @@ pip hash Usage ===== -.. pip-command-usage:: hash +.. tabs:: + + .. group-tab:: Unix/macOS + + .. pip-command-usage:: hash "python -m pip" + + .. group-tab:: Windows + + .. pip-command-usage:: hash "py -m pip" Description @@ -39,13 +47,32 @@ Options Example ======= -Compute the hash of a downloaded archive:: +Compute the hash of a downloaded archive: + +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: console + + $ python -m pip download SomePackage + Collecting SomePackage + Downloading SomePackage-2.2.tar.gz + Saved ./pip_downloads/SomePackage-2.2.tar.gz + Successfully downloaded SomePackage + $ python -m pip hash ./pip_downloads/SomePackage-2.2.tar.gz + ./pip_downloads/SomePackage-2.2.tar.gz: + --hash=sha256:93e62e05c7ad3da1a233def6731e8285156701e3419a5fe279017c429ec67ce0 + + .. group-tab:: Windows + + .. code-block:: console - $ pip download SomePackage - Collecting SomePackage - Downloading SomePackage-2.2.tar.gz - Saved ./pip_downloads/SomePackage-2.2.tar.gz - Successfully downloaded SomePackage - $ pip hash ./pip_downloads/SomePackage-2.2.tar.gz - ./pip_downloads/SomePackage-2.2.tar.gz: - --hash=sha256:93e62e05c7ad3da1a233def6731e8285156701e3419a5fe279017c429ec67ce0 + C:\> py -m pip download SomePackage + Collecting SomePackage + Downloading SomePackage-2.2.tar.gz + Saved ./pip_downloads/SomePackage-2.2.tar.gz + Successfully downloaded SomePackage + C:\> py -m pip hash ./pip_downloads/SomePackage-2.2.tar.gz + ./pip_downloads/SomePackage-2.2.tar.gz: + --hash=sha256:93e62e05c7ad3da1a233def6731e8285156701e3419a5fe279017c429ec67ce0 diff --git a/docs/html/reference/pip_install.rst b/docs/html/reference/pip_install.rst index fd962cd3658..cb97c8ee075 100644 --- a/docs/html/reference/pip_install.rst +++ b/docs/html/reference/pip_install.rst @@ -10,7 +10,16 @@ pip install Usage ===== -.. pip-command-usage:: install +.. tabs:: + + .. group-tab:: Unix/macOS + + .. pip-command-usage:: install "python -m pip" + + .. group-tab:: Windows + + .. pip-command-usage:: install "py -m pip" + Description @@ -89,15 +98,33 @@ implementation (which might possibly change later) has it such that the first encountered member of the cycle is installed last. For instance, if quux depends on foo which depends on bar which depends on baz, -which depends on foo:: +which depends on foo: + +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: console + + $ python -m pip install quux + ... + Installing collected packages baz, bar, foo, quux - pip install quux - ... - Installing collected packages baz, bar, foo, quux + $ python -m pip install bar + ... + Installing collected packages foo, baz, bar - pip install bar - ... - Installing collected packages foo, baz, bar + .. group-tab:: Windows + + .. code-block:: console + + C:\> py -m pip install quux + ... + Installing collected packages baz, bar, foo, quux + + C:\> py -m pip install bar + ... + Installing collected packages foo, baz, bar Prior to v6.1.0, pip made no commitments about install order. @@ -387,9 +414,21 @@ If your repository layout is:: └── some_file some_other_file -Then, to install from this repository, the syntax would be:: +Then, to install from this repository, the syntax would be: + +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python -m pip install -e "vcs+protocol://repo_url/#egg=pkg&subdirectory=pkg_dir" + + .. group-tab:: Windows - $ pip install -e "vcs+protocol://repo_url/#egg=pkg&subdirectory=pkg_dir" + .. code-block:: shell + + py -m pip install -e "vcs+protocol://repo_url/#egg=pkg&subdirectory=pkg_dir" Git @@ -636,17 +675,38 @@ against any requirement not only checks that hash but also activates a global .. _`--require-hashes`: Hash-checking mode can be forced on with the ``--require-hashes`` command-line -option:: - - $ pip install --require-hashes -r requirements.txt - ... - Hashes are required in --require-hashes mode (implicitly on when a hash is - specified for any package). These requirements were missing hashes, - leaving them open to tampering. These are the hashes the downloaded - archives actually had. You can add lines like these to your requirements - files to prevent tampering. - pyelasticsearch==1.0 --hash=sha256:44ddfb1225054d7d6b1d02e9338e7d4809be94edbe9929a2ec0807d38df993fa - more-itertools==2.2 --hash=sha256:93e62e05c7ad3da1a233def6731e8285156701e3419a5fe279017c429ec67ce0 +option: + +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: console + + $ python -m pip install --require-hashes -r requirements.txt + ... + Hashes are required in --require-hashes mode (implicitly on when a hash is + specified for any package). These requirements were missing hashes, + leaving them open to tampering. These are the hashes the downloaded + archives actually had. You can add lines like these to your requirements + files to prevent tampering. + pyelasticsearch==1.0 --hash=sha256:44ddfb1225054d7d6b1d02e9338e7d4809be94edbe9929a2ec0807d38df993fa + more-itertools==2.2 --hash=sha256:93e62e05c7ad3da1a233def6731e8285156701e3419a5fe279017c429ec67ce0 + + .. group-tab:: Windows + + .. code-block:: console + + C:\> py -m pip install --require-hashes -r requirements.txt + ... + Hashes are required in --require-hashes mode (implicitly on when a hash is + specified for any package). These requirements were missing hashes, + leaving them open to tampering. These are the hashes the downloaded + archives actually had. You can add lines like these to your requirements + files to prevent tampering. + pyelasticsearch==1.0 --hash=sha256:44ddfb1225054d7d6b1d02e9338e7d4809be94edbe9929a2ec0807d38df993fa + more-itertools==2.2 --hash=sha256:93e62e05c7ad3da1a233def6731e8285156701e3419a5fe279017c429ec67ce0 + This can be useful in deploy scripts, to ensure that the author of the requirements file provided hashes. It is also a convenient way to bootstrap @@ -692,14 +752,38 @@ Hash-checking mode also works with :ref:`pip download` and :ref:`pip wheel`. A as your project evolves. To be safe, install your project using pip and :ref:`--no-deps `. - Instead of ``python setup.py develop``, use... :: + Instead of ``python setup.py develop``, use... + + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python -m pip install --no-deps -e . + + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip install --no-deps -e . + - pip install --no-deps -e . + Instead of ``python setup.py install``, use... - Instead of ``python setup.py install``, use... :: + .. tabs:: - pip install --no-deps . + .. group-tab:: Unix/macOS + .. code-block:: shell + + python -m pip install --no-deps . + + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip install --no-deps . Hashes from PyPI ^^^^^^^^^^^^^^^^ @@ -717,9 +801,22 @@ Local project installs ---------------------- pip supports installing local project in both regular mode and editable mode. -You can install local projects by specifying the project path to pip:: +You can install local projects by specifying the project path to pip: + +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python -m pip install path/to/SomeProject + + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip install path/to/SomeProject -$ pip install path/to/SomeProject During regular installation, pip will copy the entire project directory to a temporary location and install from there. The exception is that pip will @@ -736,10 +833,24 @@ being copied. `_ installs. -You can install local projects or VCS projects in "editable" mode:: +You can install local projects or VCS projects in "editable" mode: + +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python -m pip install -e path/to/SomeProject + python -m pip install -e git+http://repo/my_project.git#egg=SomeProject + + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip install -e path/to/SomeProject + py -m pip install -e git+http://repo/my_project.git#egg=SomeProject -$ pip install -e path/to/SomeProject -$ pip install -e git+http://repo/my_project.git#egg=SomeProject (See the :ref:`VCS Support` section above for more information on VCS-related syntax.) @@ -846,113 +957,292 @@ Examples #. Install ``SomePackage`` and its dependencies from `PyPI`_ using :ref:`Requirement Specifiers` - :: + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python -m pip install SomePackage # latest version + python -m pip install SomePackage==1.0.4 # specific version + python -m pip install 'SomePackage>=1.0.4' # minimum version + + .. group-tab:: Windows - $ pip install SomePackage # latest version - $ pip install SomePackage==1.0.4 # specific version - $ pip install 'SomePackage>=1.0.4' # minimum version + .. code-block:: shell + + py -m pip install SomePackage # latest version + py -m pip install SomePackage==1.0.4 # specific version + py -m pip install 'SomePackage>=1.0.4' # minimum version #. Install a list of requirements specified in a file. See the :ref:`Requirements files `. - :: + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python -m pip install -r requirements.txt - $ pip install -r requirements.txt + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip install -r requirements.txt #. Upgrade an already installed ``SomePackage`` to the latest from PyPI. - :: + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell - $ pip install --upgrade SomePackage + python -m pip install --upgrade SomePackage + + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip install --upgrade SomePackage #. Install a local project in "editable" mode. See the section on :ref:`Editable Installs `. - :: + .. tabs:: + + .. group-tab:: Unix/macOS - $ pip install -e . # project in current directory - $ pip install -e path/to/project # project in another directory + .. code-block:: shell + + python -m pip install -e . # project in current directory + python -m pip install -e path/to/project # project in another directory + + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip install -e . # project in current directory + py -m pip install -e path/to/project # project in another directory #. Install a project from VCS - :: + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python -m pip install SomeProject@git+https://git.repo/some_pkg.git@1.3.1 + + .. group-tab:: Windows + + .. code-block:: shell - $ pip install SomeProject@git+https://git.repo/some_pkg.git@1.3.1 + py -m pip install SomeProject@git+https://git.repo/some_pkg.git@1.3.1 #. Install a project from VCS in "editable" mode. See the sections on :ref:`VCS Support ` and :ref:`Editable Installs `. - :: + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python -m pip install -e git+https://git.repo/some_pkg.git#egg=SomePackage # from git + python -m pip install -e hg+https://hg.repo/some_pkg.git#egg=SomePackage # from mercurial + python -m python -m pip install -e svn+svn://svn.repo/some_pkg/trunk/#egg=SomePackage # from svn + python -m pip install -e git+https://git.repo/some_pkg.git@feature#egg=SomePackage # from 'feature' branch + python -m pip install -e "git+https://git.repo/some_repo.git#egg=subdir&subdirectory=subdir_path" # install a python package from a repo subdirectory + + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip install -e git+https://git.repo/some_pkg.git#egg=SomePackage # from git + py -m pip install -e hg+https://hg.repo/some_pkg.git#egg=SomePackage # from mercurial + py -m pip install -e svn+svn://svn.repo/some_pkg/trunk/#egg=SomePackage # from svn + py -m pip install -e git+https://git.repo/some_pkg.git@feature#egg=SomePackage # from 'feature' branch + py -m pip install -e "git+https://git.repo/some_repo.git#egg=subdir&subdirectory=subdir_path" # install a python package from a repo subdirectory - $ pip install -e git+https://git.repo/some_pkg.git#egg=SomePackage # from git - $ pip install -e hg+https://hg.repo/some_pkg.git#egg=SomePackage # from mercurial - $ pip install -e svn+svn://svn.repo/some_pkg/trunk/#egg=SomePackage # from svn - $ pip install -e git+https://git.repo/some_pkg.git@feature#egg=SomePackage # from 'feature' branch - $ pip install -e "git+https://git.repo/some_repo.git#egg=subdir&subdirectory=subdir_path" # install a python package from a repo subdirectory #. Install a package with `setuptools extras`_. - :: + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell - $ pip install SomePackage[PDF] - $ pip install "SomePackage[PDF] @ git+https://git.repo/SomePackage@master#subdirectory=subdir_path" - $ pip install .[PDF] # project in current directory - $ pip install SomePackage[PDF]==3.0 - $ pip install SomePackage[PDF,EPUB] # multiple extras + python -m pip install SomePackage[PDF] + python -m pip install "SomePackage[PDF] @ git+https://git.repo/SomePackage@master#subdirectory=subdir_path" + python -m pip install .[PDF] # project in current directory + python -m pip install SomePackage[PDF]==3.0 + python -m pip install SomePackage[PDF,EPUB] # multiple extras + + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip install SomePackage[PDF] + py -m pip install "SomePackage[PDF] @ git+https://git.repo/SomePackage@master#subdirectory=subdir_path" + py -m pip install .[PDF] # project in current directory + py -m pip install SomePackage[PDF]==3.0 + py -m pip install SomePackage[PDF,EPUB] # multiple extras #. Install a particular source archive file. - :: + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell - $ pip install ./downloads/SomePackage-1.0.4.tar.gz - $ pip install http://my.package.repo/SomePackage-1.0.4.zip + python -m pip install ./downloads/SomePackage-1.0.4.tar.gz + python -m pip install http://my.package.repo/SomePackage-1.0.4.zip + + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip install ./downloads/SomePackage-1.0.4.tar.gz + py -m pip install http://my.package.repo/SomePackage-1.0.4.zip #. Install a particular source archive file following :pep:`440` direct references. - :: + .. tabs:: + + .. group-tab:: Unix/macOS - $ pip install SomeProject@http://my.package.repo/SomeProject-1.2.3-py33-none-any.whl - $ pip install "SomeProject @ http://my.package.repo/SomeProject-1.2.3-py33-none-any.whl" - $ pip install SomeProject@http://my.package.repo/1.2.3.tar.gz + .. code-block:: shell + + python -m pip install SomeProject@http://my.package.repo/SomeProject-1.2.3-py33-none-any.whl + python -m pip install "SomeProject @ http://my.package.repo/SomeProject-1.2.3-py33-none-any.whl" + python -m pip install SomeProject@http://my.package.repo/1.2.3.tar.gz + + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip install SomeProject@http://my.package.repo/SomeProject-1.2.3-py33-none-any.whl + py -m pip install "SomeProject @ http://my.package.repo/SomeProject-1.2.3-py33-none-any.whl" + py -m pip install SomeProject@http://my.package.repo/1.2.3.tar.gz #. Install from alternative package repositories. - Install from a different index, and not `PyPI`_ :: + Install from a different index, and not `PyPI`_ + + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python -m pip install --index-url http://my.package.repo/simple/ SomePackage - $ pip install --index-url http://my.package.repo/simple/ SomePackage + .. group-tab:: Windows - Search an additional index during install, in addition to `PyPI`_ :: + .. code-block:: shell - $ pip install --extra-index-url http://my.package.repo/simple SomePackage + py -m pip install --index-url http://my.package.repo/simple/ SomePackage - Install from a local flat directory containing archives (and don't scan indexes):: - $ pip install --no-index --find-links=file:///local/dir/ SomePackage - $ pip install --no-index --find-links=/local/dir/ SomePackage - $ pip install --no-index --find-links=relative/dir/ SomePackage + Search an additional index during install, in addition to `PyPI`_ + + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python -m pip install --extra-index-url http://my.package.repo/simple SomePackage + + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip install --extra-index-url http://my.package.repo/simple SomePackage + + + Install from a local flat directory containing archives (and don't scan indexes): + + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python -m pip install --no-index --find-links=file:///local/dir/ SomePackage + python -m pip install --no-index --find-links=/local/dir/ SomePackage + python -m pip install --no-index --find-links=relative/dir/ SomePackage + + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip install --no-index --find-links=file:///local/dir/ SomePackage + py -m pip install --no-index --find-links=/local/dir/ SomePackage + py -m pip install --no-index --find-links=relative/dir/ SomePackage #. Find pre-release and development versions, in addition to stable versions. By default, pip only finds stable versions. - :: + .. tabs:: + + .. group-tab:: Unix/macOS - $ pip install --pre SomePackage + .. code-block:: shell + + python -m pip install --pre SomePackage + + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip install --pre SomePackage #. Install packages from source. - Do not use any binary packages:: + Do not use any binary packages + + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python -m pip install SomePackage1 SomePackage2 --no-binary :all: + + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip install SomePackage1 SomePackage2 --no-binary :all: + + Specify ``SomePackage1`` to be installed from source: + + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python -m pip install SomePackage1 SomePackage2 --no-binary SomePackage1 - $ pip install SomePackage1 SomePackage2 --no-binary :all: + .. group-tab:: Windows - Specify ``SomePackage1`` to be installed from source:: + .. code-block:: shell - $ pip install SomePackage1 SomePackage2 --no-binary SomePackage1 + py -m pip install SomePackage1 SomePackage2 --no-binary SomePackage1 ---- diff --git a/docs/html/reference/pip_list.rst b/docs/html/reference/pip_list.rst index 15d0920a7f2..1489ed751a1 100644 --- a/docs/html/reference/pip_list.rst +++ b/docs/html/reference/pip_list.rst @@ -10,7 +10,15 @@ pip list Usage ===== -.. pip-command-usage:: list +.. tabs:: + + .. group-tab:: Unix/macOS + + .. pip-command-usage:: list "python -m pip" + + .. group-tab:: Windows + + .. pip-command-usage:: list "py -m pip" Description @@ -32,75 +40,182 @@ Examples #. List installed packages. - :: + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: console - $ pip list - docutils (0.10) - Jinja2 (2.7.2) - MarkupSafe (0.18) - Pygments (1.6) - Sphinx (1.2.1) + $ python -m pip list + docutils (0.10) + Jinja2 (2.7.2) + MarkupSafe (0.18) + Pygments (1.6) + Sphinx (1.2.1) + + .. group-tab:: Windows + + .. code-block:: console + + C:\> py -m pip list + docutils (0.10) + Jinja2 (2.7.2) + MarkupSafe (0.18) + Pygments (1.6) + Sphinx (1.2.1) #. List outdated packages (excluding editables), and the latest version available. - :: + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: console + + $ python -m pip list --outdated + docutils (Current: 0.10 Latest: 0.11) + Sphinx (Current: 1.2.1 Latest: 1.2.2) + + .. group-tab:: Windows + + .. code-block:: console + + C:\> py -m pip list --outdated + docutils (Current: 0.10 Latest: 0.11) + Sphinx (Current: 1.2.1 Latest: 1.2.2) - $ pip list --outdated - docutils (Current: 0.10 Latest: 0.11) - Sphinx (Current: 1.2.1 Latest: 1.2.2) #. List installed packages with column formatting. - :: + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: console + + $ python -m pip list --format columns + Package Version + ------- ------- + docopt 0.6.2 + idlex 1.13 + jedi 0.9.0 - $ pip list --format columns - Package Version - ------- ------- - docopt 0.6.2 - idlex 1.13 - jedi 0.9.0 + .. group-tab:: Windows + + .. code-block:: console + + C:\> py -m pip list --format columns + Package Version + ------- ------- + docopt 0.6.2 + idlex 1.13 + jedi 0.9.0 #. List outdated packages with column formatting. - :: + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: console + + $ python -m pip list -o --format columns + Package Version Latest Type + ---------- ------- ------ ----- + retry 0.8.1 0.9.1 wheel + setuptools 20.6.7 21.0.0 wheel - $ pip list -o --format columns - Package Version Latest Type - ---------- ------- ------ ----- - retry 0.8.1 0.9.1 wheel - setuptools 20.6.7 21.0.0 wheel + .. group-tab:: Windows + + .. code-block:: console + + C:\> py -m pip list -o --format columns + Package Version Latest Type + ---------- ------- ------ ----- + retry 0.8.1 0.9.1 wheel + setuptools 20.6.7 21.0.0 wheel #. List packages that are not dependencies of other packages. Can be combined with other options. - :: + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: console + + $ python -m pip list --outdated --not-required + docutils (Current: 0.10 Latest: 0.11) + + .. group-tab:: Windows - $ pip list --outdated --not-required - docutils (Current: 0.10 Latest: 0.11) + .. code-block:: console + + C:\> py -m pip list --outdated --not-required + docutils (Current: 0.10 Latest: 0.11) #. Use legacy formatting - :: + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: console + + $ python -m pip list --format=legacy + colorama (0.3.7) + docopt (0.6.2) + idlex (1.13) + jedi (0.9.0) + + .. group-tab:: Windows - $ pip list --format=legacy - colorama (0.3.7) - docopt (0.6.2) - idlex (1.13) - jedi (0.9.0) + .. code-block:: console + + C:\> py -m pip list --format=legacy + colorama (0.3.7) + docopt (0.6.2) + idlex (1.13) + jedi (0.9.0) #. Use json formatting - :: + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: console + + $ python -m pip list --format=json + [{'name': 'colorama', 'version': '0.3.7'}, {'name': 'docopt', 'version': '0.6.2'}, ... + + .. group-tab:: Windows + + .. code-block:: console - $ pip list --format=json - [{'name': 'colorama', 'version': '0.3.7'}, {'name': 'docopt', 'version': '0.6.2'}, ... + C:\> py -m pip list --format=json + [{'name': 'colorama', 'version': '0.3.7'}, {'name': 'docopt', 'version': '0.6.2'}, ... #. Use freeze formatting - :: + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: console + + $ python -m pip list --format=freeze + colorama==0.3.7 + docopt==0.6.2 + idlex==1.13 + jedi==0.9.0 + + .. group-tab:: Windows + + .. code-block:: console - $ pip list --format=freeze - colorama==0.3.7 - docopt==0.6.2 - idlex==1.13 - jedi==0.9.0 + C:\> py -m pip list --format=freeze + colorama==0.3.7 + docopt==0.6.2 + idlex==1.13 + jedi==0.9.0 diff --git a/docs/html/reference/pip_search.rst b/docs/html/reference/pip_search.rst index db1bd2be806..fba62959316 100644 --- a/docs/html/reference/pip_search.rst +++ b/docs/html/reference/pip_search.rst @@ -10,7 +10,15 @@ pip search Usage ===== -.. pip-command-usage:: search +.. tabs:: + + .. group-tab:: Unix/macOS + + .. pip-command-usage:: search "python -m pip" + + .. group-tab:: Windows + + .. pip-command-usage:: search "py -m pip" Description @@ -30,8 +38,20 @@ Examples #. Search for "peppercorn" - :: + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: console + + $ python -m pip search peppercorn + pepperedform - Helpers for using peppercorn with formprocess. + peppercorn - A library for converting a token stream into [...] + + .. group-tab:: Windows + + .. code-block:: console - $ pip search peppercorn - pepperedform - Helpers for using peppercorn with formprocess. - peppercorn - A library for converting a token stream into [...] + C:\> py -m pip search peppercorn + pepperedform - Helpers for using peppercorn with formprocess. + peppercorn - A library for converting a token stream into [...] diff --git a/docs/html/reference/pip_show.rst b/docs/html/reference/pip_show.rst index e9568b6b098..6bd3718b95d 100644 --- a/docs/html/reference/pip_show.rst +++ b/docs/html/reference/pip_show.rst @@ -10,7 +10,15 @@ pip show Usage ===== -.. pip-command-usage:: show +.. tabs:: + + .. group-tab:: Unix/macOS + + .. pip-command-usage:: show "python -m pip" + + .. group-tab:: Windows + + .. pip-command-usage:: show "py -m pip" Description @@ -30,58 +38,124 @@ Examples #. Show information about a package: - :: + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: console + + $ python -m pip show sphinx + Name: Sphinx + Version: 1.4.5 + Summary: Python documentation generator + Home-page: http://sphinx-doc.org/ + Author: Georg Brandl + Author-email: georg@python.org + License: BSD + Location: /my/env/lib/python2.7/site-packages + Requires: docutils, snowballstemmer, alabaster, Pygments, imagesize, Jinja2, babel, six + + .. group-tab:: Windows + + .. code-block:: console - $ pip show sphinx - Name: Sphinx - Version: 1.4.5 - Summary: Python documentation generator - Home-page: http://sphinx-doc.org/ - Author: Georg Brandl - Author-email: georg@python.org - License: BSD - Location: /my/env/lib/python2.7/site-packages - Requires: docutils, snowballstemmer, alabaster, Pygments, imagesize, Jinja2, babel, six + C:\> py -m pip show sphinx + Name: Sphinx + Version: 1.4.5 + Summary: Python documentation generator + Home-page: http://sphinx-doc.org/ + Author: Georg Brandl + Author-email: georg@python.org + License: BSD + Location: /my/env/lib/python2.7/site-packages + Requires: docutils, snowballstemmer, alabaster, Pygments, imagesize, Jinja2, babel, six #. Show all information about a package - :: - - $ pip show --verbose sphinx - Name: Sphinx - Version: 1.4.5 - Summary: Python documentation generator - Home-page: http://sphinx-doc.org/ - Author: Georg Brandl - Author-email: georg@python.org - License: BSD - Location: /my/env/lib/python2.7/site-packages - Requires: docutils, snowballstemmer, alabaster, Pygments, imagesize, Jinja2, babel, six - Metadata-Version: 2.0 - Installer: - Classifiers: - Development Status :: 5 - Production/Stable - Environment :: Console - Environment :: Web Environment - Intended Audience :: Developers - Intended Audience :: Education - License :: OSI Approved :: BSD License - Operating System :: OS Independent - Programming Language :: Python - Programming Language :: Python :: 2 - Programming Language :: Python :: 3 - Framework :: Sphinx - Framework :: Sphinx :: Extension - Framework :: Sphinx :: Theme - Topic :: Documentation - Topic :: Documentation :: Sphinx - Topic :: Text Processing - Topic :: Utilities - Entry-points: - [console_scripts] - sphinx-apidoc = sphinx.apidoc:main - sphinx-autogen = sphinx.ext.autosummary.generate:main - sphinx-build = sphinx:main - sphinx-quickstart = sphinx.quickstart:main - [distutils.commands] - build_sphinx = sphinx.setup_command:BuildDoc + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: console + + $ python -m pip show --verbose sphinx + Name: Sphinx + Version: 1.4.5 + Summary: Python documentation generator + Home-page: http://sphinx-doc.org/ + Author: Georg Brandl + Author-email: georg@python.org + License: BSD + Location: /my/env/lib/python2.7/site-packages + Requires: docutils, snowballstemmer, alabaster, Pygments, imagesize, Jinja2, babel, six + Metadata-Version: 2.0 + Installer: + Classifiers: + Development Status :: 5 - Production/Stable + Environment :: Console + Environment :: Web Environment + Intended Audience :: Developers + Intended Audience :: Education + License :: OSI Approved :: BSD License + Operating System :: OS Independent + Programming Language :: Python + Programming Language :: Python :: 2 + Programming Language :: Python :: 3 + Framework :: Sphinx + Framework :: Sphinx :: Extension + Framework :: Sphinx :: Theme + Topic :: Documentation + Topic :: Documentation :: Sphinx + Topic :: Text Processing + Topic :: Utilities + Entry-points: + [console_scripts] + sphinx-apidoc = sphinx.apidoc:main + sphinx-autogen = sphinx.ext.autosummary.generate:main + sphinx-build = sphinx:main + sphinx-quickstart = sphinx.quickstart:main + [distutils.commands] + build_sphinx = sphinx.setup_command:BuildDoc + + .. group-tab:: Windows + + .. code-block:: console + + C:\> py -m pip show --verbose sphinx + Name: Sphinx + Version: 1.4.5 + Summary: Python documentation generator + Home-page: http://sphinx-doc.org/ + Author: Georg Brandl + Author-email: georg@python.org + License: BSD + Location: /my/env/lib/python2.7/site-packages + Requires: docutils, snowballstemmer, alabaster, Pygments, imagesize, Jinja2, babel, six + Metadata-Version: 2.0 + Installer: + Classifiers: + Development Status :: 5 - Production/Stable + Environment :: Console + Environment :: Web Environment + Intended Audience :: Developers + Intended Audience :: Education + License :: OSI Approved :: BSD License + Operating System :: OS Independent + Programming Language :: Python + Programming Language :: Python :: 2 + Programming Language :: Python :: 3 + Framework :: Sphinx + Framework :: Sphinx :: Extension + Framework :: Sphinx :: Theme + Topic :: Documentation + Topic :: Documentation :: Sphinx + Topic :: Text Processing + Topic :: Utilities + Entry-points: + [console_scripts] + sphinx-apidoc = sphinx.apidoc:main + sphinx-autogen = sphinx.ext.autosummary.generate:main + sphinx-build = sphinx:main + sphinx-quickstart = sphinx.quickstart:main + [distutils.commands] + build_sphinx = sphinx.setup_command:BuildDoc diff --git a/docs/html/reference/pip_uninstall.rst b/docs/html/reference/pip_uninstall.rst index 67d752d6b97..8b31c5673c1 100644 --- a/docs/html/reference/pip_uninstall.rst +++ b/docs/html/reference/pip_uninstall.rst @@ -10,7 +10,15 @@ pip uninstall Usage ===== -.. pip-command-usage:: uninstall +.. tabs:: + + .. group-tab:: Unix/macOS + + .. pip-command-usage:: uninstall "python -m pip" + + .. group-tab:: Windows + + .. pip-command-usage:: uninstall "py -m pip" Description @@ -30,11 +38,26 @@ Examples #. Uninstall a package. - :: + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: console + + $ python -m pip uninstall simplejson + Uninstalling simplejson: + /home/me/env/lib/python2.7/site-packages/simplejson + /home/me/env/lib/python2.7/site-packages/simplejson-2.2.1-py2.7.egg-info + Proceed (y/n)? y + Successfully uninstalled simplejson + + .. group-tab:: Windows + + .. code-block:: console - $ pip uninstall simplejson - Uninstalling simplejson: - /home/me/env/lib/python2.7/site-packages/simplejson - /home/me/env/lib/python2.7/site-packages/simplejson-2.2.1-py2.7.egg-info - Proceed (y/n)? y - Successfully uninstalled simplejson + C:\> py -m pip uninstall simplejson + Uninstalling simplejson: + /home/me/env/lib/python2.7/site-packages/simplejson + /home/me/env/lib/python2.7/site-packages/simplejson-2.2.1-py2.7.egg-info + Proceed (y/n)? y + Successfully uninstalled simplejson diff --git a/docs/html/reference/pip_wheel.rst b/docs/html/reference/pip_wheel.rst index dc32dda463c..c1bdf37f852 100644 --- a/docs/html/reference/pip_wheel.rst +++ b/docs/html/reference/pip_wheel.rst @@ -11,7 +11,15 @@ pip wheel Usage ===== -.. pip-command-usage:: wheel +.. tabs:: + + .. group-tab:: Unix/macOS + + .. pip-command-usage:: wheel "python -m pip" + + .. group-tab:: Windows + + .. pip-command-usage:: wheel "py -m pip" Description @@ -24,9 +32,22 @@ Build System Interface ---------------------- In order for pip to build a wheel, ``setup.py`` must implement the -``bdist_wheel`` command with the following syntax:: +``bdist_wheel`` command with the following syntax: + +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python setup.py bdist_wheel -d TARGET + + .. group-tab:: Windows + + .. code-block:: shell + + py setup.py bdist_wheel -d TARGET - python setup.py bdist_wheel -d TARGET This command must create a wheel compatible with the invoking Python interpreter, and save that wheel in the directory TARGET. @@ -39,9 +60,22 @@ Customising the build It is possible using ``--global-option`` to include additional build commands with their arguments in the ``setup.py`` command. This is currently the only way to influence the building of C extensions from the command line. For -example:: +example: + +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python -m pip wheel --global-option bdist_ext --global-option -DFOO wheel + + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip wheel --global-option bdist_ext --global-option -DFOO wheel - pip wheel --global-option bdist_ext --global-option -DFOO wheel will result in a build command of @@ -69,13 +103,34 @@ Examples #. Build wheels for a requirement (and all its dependencies), and then install - :: + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python -m pip wheel --wheel-dir=/tmp/wheelhouse SomePackage + python -m pip install --no-index --find-links=/tmp/wheelhouse SomePackage - $ pip wheel --wheel-dir=/tmp/wheelhouse SomePackage - $ pip install --no-index --find-links=/tmp/wheelhouse SomePackage + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip wheel --wheel-dir=/tmp/wheelhouse SomePackage + py -m pip install --no-index --find-links=/tmp/wheelhouse SomePackage #. Build a wheel for a package from source - :: + .. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python -m pip wheel --no-binary SomePackage SomePackage + + .. group-tab:: Windows + + .. code-block:: shell - $ pip wheel --no-binary SomePackage SomePackage + py -m pip wheel --no-binary SomePackage SomePackage diff --git a/docs/html/user_guide.rst b/docs/html/user_guide.rst index ce013c2a362..64edc0b1887 100644 --- a/docs/html/user_guide.rst +++ b/docs/html/user_guide.rst @@ -9,23 +9,28 @@ Running pip =========== 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:: +to your system, which can be run from the command prompt as follows: - $ pip +.. tabs:: -If you cannot run the ``pip`` command directly (possibly because the location -where it was installed isn't on your operating system's ``PATH``) then you can -run pip via the Python interpreter:: + .. group-tab:: Unix/macOS - $ python -m pip + .. code-block:: shell -On Windows, the ``py`` launcher can be used:: + python -m pip - $ py -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. -Even though pip is available from your Python installation as an importable -module, via ``import pip``, it is *not supported* to use pip in this way. For -more details, see :ref:`Using pip from your program`. + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip + + ``py -m pip`` executes pip using the latest Python interpreter you + have installed. For more details, read the `Python Windows launcher`_ docs. Installing Packages @@ -36,12 +41,25 @@ directly from distribution files. The most common scenario is to install from `PyPI`_ using :ref:`Requirement -Specifiers` :: +Specifiers` + +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell - $ pip install SomePackage # latest version - $ pip install SomePackage==1.0.4 # specific version - $ pip install 'SomePackage>=1.0.4' # minimum version + python -m pip install SomePackage # latest version + python -m pip install SomePackage==1.0.4 # specific version + python -m pip install 'SomePackage>=1.0.4' # minimum version + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip install SomePackage # latest version + 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. @@ -142,10 +160,21 @@ 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: + +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell - pip install -r requirements.txt + python -m pip install -r requirements.txt + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip install -r requirements.txt Details on the format of the files are here: :ref:`Requirements File Format`. @@ -160,10 +189,21 @@ In practice, there are 4 common uses of Requirements files: this case, your requirement file contains a pinned version of everything that was installed when ``pip freeze`` was run. - :: +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python -m pip freeze > requirements.txt + python -m pip install -r requirements.txt - pip freeze > requirements.txt - pip install -r requirements.txt + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip freeze > requirements.txt + py -m pip install -r requirements.txt 2. Requirements files are used to force pip to properly resolve dependencies. As it is now, pip `doesn't have true dependency resolution @@ -228,9 +268,21 @@ contents is nearly identical to :ref:`Requirements Files`. There is one key difference: Including a package in a constraints file does not trigger installation of the package. -Use a constraints file like so:: +Use a constraints file like so: + +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell - pip install -c constraints.txt + python -m pip install -c constraints.txt + + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip install -c constraints.txt Constraints files are used for exactly the same reason as requirements files when you don't know exactly what things you want to install. For instance, say @@ -268,9 +320,19 @@ archives. To install directly from a wheel archive: -:: +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell - pip install SomePackage-1.0-py2.py3-none-any.whl + python -m pip install SomePackage-1.0-py2.py3-none-any.whl + + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip install SomePackage-1.0-py2.py3-none-any.whl For the cases where wheels are not available, pip offers :ref:`pip wheel` as a @@ -283,17 +345,38 @@ convenience, to build wheels for all your requirements and dependencies. To build wheels for your requirements and all their dependencies to a local directory: -:: +.. tabs:: + + .. group-tab:: Unix/macOS - pip install wheel - pip wheel --wheel-dir=/local/wheels -r requirements.txt + .. code-block:: shell + + python -m pip install wheel + python -m pip wheel --wheel-dir=/local/wheels -r requirements.txt + + .. group-tab:: Windows + + .. code-block:: shell + + 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 wheels (and not from PyPI): -:: +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python -m pip install --no-index --find-links=/local/wheels -r requirements.txt + + .. group-tab:: Windows + + .. code-block:: shell - pip install --no-index --find-links=/local/wheels -r requirements.txt + py -m pip install --no-index --find-links=/local/wheels -r requirements.txt Uninstalling Packages @@ -301,9 +384,20 @@ Uninstalling Packages pip is able to uninstall most packages like so: -:: +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python -m pip uninstall SomePackage + + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip uninstall SomePackage - $ pip uninstall SomePackage pip also performs an automatic uninstall of an old version of a package before upgrading to a newer version. @@ -316,33 +410,74 @@ Listing Packages To list installed packages: -:: +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: console + + $ python -m pip list + docutils (0.9.1) + Jinja2 (2.6) + Pygments (1.5) + Sphinx (1.1.2) + + .. group-tab:: Windows + + .. code-block:: console + + C:\> py -m pip list + docutils (0.9.1) + Jinja2 (2.6) + Pygments (1.5) + Sphinx (1.1.2) - $ pip list - docutils (0.9.1) - Jinja2 (2.6) - Pygments (1.5) - Sphinx (1.1.2) To list outdated packages, and show the latest version available: -:: +.. tabs:: + + .. group-tab:: Unix/macOS - $ pip list --outdated - docutils (Current: 0.9.1 Latest: 0.10) - Sphinx (Current: 1.1.2 Latest: 1.1.3) + .. code-block:: console + $ python -m pip list --outdated + docutils (Current: 0.9.1 Latest: 0.10) + Sphinx (Current: 1.1.2 Latest: 1.1.3) + + .. group-tab:: Windows + + .. code-block:: console + + C:\> py -m pip list --outdated + docutils (Current: 0.9.1 Latest: 0.10) + Sphinx (Current: 1.1.2 Latest: 1.1.3) To show details about an installed package: -:: +.. tabs:: + + .. group-tab:: Unix/macOS - $ pip show sphinx - --- - Name: Sphinx - Version: 1.1.3 - Location: /my/env/lib/pythonx.x/site-packages - Requires: Pygments, Jinja2, docutils + .. code-block:: console + + $ python -m pip show sphinx + --- + Name: Sphinx + Version: 1.1.3 + Location: /my/env/lib/pythonx.x/site-packages + Requires: Pygments, Jinja2, docutils + + .. group-tab:: Windows + + .. code-block:: console + + C:\> py -m pip show sphinx + --- + Name: Sphinx + Version: 1.1.3 + 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` @@ -353,9 +488,21 @@ Searching for Packages ====================== pip can search `PyPI`_ for packages using the ``pip search`` -command:: +command: + +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python -m pip search "query" + + .. group-tab:: Windows + + .. code-block:: shell - $ pip search "query" + py -m pip search "query" The query will be used to search the names and summaries of all packages. @@ -515,22 +662,72 @@ pip's command line options can be set with environment variables using the format ``PIP_`` . Dashes (``-``) have to be replaced with underscores (``_``). -For example, to set the default timeout:: +For example, to set the default timeout: + +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + export PIP_DEFAULT_TIMEOUT=60 + + .. group-tab:: Windows + + .. code-block:: shell + + set PIP_DEFAULT_TIMEOUT=60 + +This is the same as passing the option to pip directly: + +.. tabs:: + + .. group-tab:: Unix/macOS - export PIP_DEFAULT_TIMEOUT=60 + .. code-block:: shell -This is the same as passing the option to pip directly:: + python -m pip --default-timeout=60 [...] - pip --default-timeout=60 [...] + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip --default-timeout=60 [...] For command line options which can be repeated, use a space to separate -multiple values. For example:: +multiple values. For example: - export PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com" +.. tabs:: -is the same as calling:: + .. group-tab:: Unix/macOS + + .. code-block:: shell + + export PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com" + + .. group-tab:: Windows + + .. code-block:: shell + + set PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com" + + +is the same as calling: + +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python -m pip install --find-links=http://mirror1.example.com --find-links=http://mirror2.example.com + + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip install --find-links=http://mirror1.example.com --find-links=http://mirror2.example.com - pip install --find-links=http://mirror1.example.com --find-links=http://mirror2.example.com Options that do not take a value, but can be repeated (such as ``--verbose``) can be specified using the number of repetitions, so:: @@ -573,15 +770,15 @@ pip comes with support for command line completion in bash, zsh and fish. To setup for bash:: - $ pip completion --bash >> ~/.profile + python -m pip completion --bash >> ~/.profile To setup for zsh:: - $ pip completion --zsh >> ~/.zprofile + python -m pip completion --zsh >> ~/.zprofile To setup for fish:: -$ pip completion --fish > ~/.config/fish/completions/pip.fish + python -m pip completion --fish > ~/.config/fish/completions/pip.fish 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 @@ -600,24 +797,59 @@ Installing from local packages In some cases, you may want to install from local packages only, with no traffic to PyPI. -First, download the archives that fulfill your requirements:: +First, download the archives that fulfill your requirements: + +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python -m pip download --destination-directory DIR -r requirements.txt -$ pip download --destination-directory DIR -r requirements.txt + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip download --destination-directory DIR -r requirements.txt 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 -this instead:: +this instead: + +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python -m pip wheel --wheel-dir DIR -r requirements.txt -$ pip wheel --wheel-dir DIR -r requirements.txt + .. group-tab:: Windows + .. code-block:: shell + + 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: + +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python -m pip install --no-index --find-links=DIR -r requirements.txt -$ pip install --no-index --find-links=DIR -r requirements.txt + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip install --no-index --find-links=DIR -r requirements.txt "Only if needed" Recursive Upgrade @@ -636,10 +868,24 @@ 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. As an historic note, an earlier "fix" for getting the ``only-if-needed`` -behaviour was:: +behaviour was: + +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python -m pip install --upgrade --no-deps SomePackage + python -m pip install SomePackage + + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip install --upgrade --no-deps SomePackage + py -m pip install SomePackage - pip install --upgrade --no-deps SomePackage - pip install SomePackage A proposal for an ``upgrade-all`` command is being considered as a safer alternative to the behaviour of eager upgrading. @@ -662,11 +908,23 @@ Moreover, the "user scheme" can be customized by setting the ``site.USER_BASE``. To install "SomePackage" into an environment with site.USER_BASE customized to -'/myappenv', do the following:: +'/myappenv', do the following: + +.. tabs:: - export PYTHONUSERBASE=/myappenv - pip install --user SomePackage + .. group-tab:: Unix/macOS + .. code-block:: shell + + export PYTHONUSERBASE=/myappenv + python -m pip install --user SomePackage + + .. group-tab:: Windows + + .. code-block:: shell + + set PYTHONUSERBASE=c:/myappenv + py -m pip install --user SomePackage ``pip install --user`` follows four rules: @@ -689,54 +947,125 @@ To install "SomePackage" into an environment with site.USER_BASE customized to 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): + +.. tabs:: + + .. group-tab:: Unix/macOS - $ pip install --user SomePackage - Can not perform a '--user' install. User site-packages are not visible in this virtualenv. + .. code-block:: console + + $ python -m pip install --user SomePackage + Can not perform a '--user' install. User site-packages are not visible in this virtualenv. + + .. group-tab:: Windows + + .. code-block:: console + + C:\> py -m pip install --user SomePackage + 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`` -is already installed in the virtualenv:: +is already installed in the virtualenv: + +.. tabs:: - $ pip install --user SomePackage==0.4 - Will not install to the user site because it will lack sys.path precedence + .. group-tab:: Unix/macOS + .. code-block:: console -From within a real python, where ``SomePackage`` is *not* installed globally:: + $ python -m pip install --user SomePackage==0.4 + Will not install to the user site because it will lack sys.path precedence - $ pip install --user SomePackage - [...] - Successfully installed SomePackage + .. group-tab:: Windows + .. code-block:: console + + 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: + +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: console + + $ python -m pip install --user SomePackage + [...] + Successfully installed SomePackage + + .. group-tab:: Windows + + .. code-block:: console + + C:\> py -m pip install --user SomePackage + [...] + Successfully installed SomePackage From within a real python, where ``SomePackage`` *is* installed globally, but -is *not* the latest version:: +is *not* the latest version: + +.. tabs:: - $ pip install --user SomePackage - [...] - Requirement already satisfied (use --upgrade to upgrade) + .. group-tab:: Unix/macOS - $ pip install --user --upgrade SomePackage - [...] - Successfully installed SomePackage + .. code-block:: console + $ python -m pip install --user SomePackage + [...] + Requirement already satisfied (use --upgrade to upgrade) + $ python -m pip install --user --upgrade SomePackage + [...] + Successfully installed SomePackage + + .. group-tab:: Windows + + .. code-block:: console + + C:\> py -m pip install --user SomePackage + [...] + Requirement already satisfied (use --upgrade to upgrade) + C:\> py -m pip install --user --upgrade SomePackage + [...] + Successfully installed SomePackage From within a real python, where ``SomePackage`` *is* installed globally, and -is the latest version:: +is the latest version: + +.. tabs:: + + .. group-tab:: Unix/macOS - $ pip install --user SomePackage - [...] - Requirement already satisfied (use --upgrade to upgrade) + .. code-block:: console - $ pip install --user --upgrade SomePackage - [...] - Requirement already up-to-date: SomePackage + $ python -m pip install --user SomePackage + [...] + Requirement already satisfied (use --upgrade to upgrade) + $ python -m pip install --user --upgrade SomePackage + [...] + Requirement already up-to-date: SomePackage + # force the install + $ python -m pip install --user --ignore-installed SomePackage + [...] + Successfully installed SomePackage - # force the install - $ pip install --user --ignore-installed SomePackage - [...] - Successfully installed SomePackage + .. group-tab:: Windows + .. code-block:: console + + C:\> py -m pip install --user SomePackage + [...] + Requirement already satisfied (use --upgrade to upgrade) + C:\> py -m pip install --user --upgrade SomePackage + [...] + Requirement already up-to-date: SomePackage + # force the install + C:\> py -m pip install --user --ignore-installed SomePackage + [...] + Successfully installed SomePackage .. _`Repeatability`: @@ -801,7 +1130,7 @@ index servers are unavailable and avoids time-consuming recompilation. Create an archive like this:: $ tempdir=$(mktemp -d /tmp/wheelhouse-XXXXX) - $ pip wheel -r requirements.txt --wheel-dir=$tempdir + $ python -m pip wheel -r requirements.txt --wheel-dir=$tempdir $ cwd=`pwd` $ (cd "$tempdir"; tar -cjvf "$cwd/bundled.tar.bz2" *) @@ -809,10 +1138,10 @@ You can then install from the archive like this:: $ tempdir=$(mktemp -d /tmp/wheelhouse-XXXXX) $ (cd $tempdir; tar -xvf /path/to/bundled.tar.bz2) - $ pip install --force-reinstall --ignore-installed --upgrade --no-index --no-deps $tempdir/* + $ python -m pip install --force-reinstall --ignore-installed --upgrade --no-index --no-deps $tempdir/* Note that compiled packages are typically OS- and architecture-specific, so -these archives are not necessarily portable across machines. +these archives are not necessarily portable across macOShines. Hash-checking mode can be used along with this method to ensure that future archives are built with identical packages. @@ -842,10 +1171,22 @@ Understanding your error message When you get a ``ResolutionImpossible`` error, you might see something like this: -.. code-block:: console +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python -m pip install package_coffee==0.44.1 package_tea==4.3.0 + + .. group-tab:: Windows + + .. code-block:: shell + + py -m pip install package_coffee==0.44.1 package_tea==4.3.0 + +:: - $ pip install package_coffee==0.44.1 package_tea==4.3.0 - ... Due to conflicting dependencies pip cannot install package_coffee and package_tea: - package_coffee depends on package_water<3.0.0,>=2.4.2 @@ -936,7 +1277,7 @@ the same version of ``package_water``, you might consider: (e.g. ``pip install "package_coffee>0.44.*" "package_tea>4.0.0"``) - Asking pip to install *any* version of ``package_coffee`` and ``package_tea`` by removing the version specifiers altogether (e.g. - ``pip install package_coffee package_tea``) + ``python -m pip install package_coffee package_tea``) In the second case, pip will automatically find a version of both ``package_coffee`` and ``package_tea`` that depend on the same version of @@ -946,9 +1287,21 @@ In the second case, pip will automatically find a version of both - ``package_tea 4.3.0`` which *also* depends on ``package_water 2.6.1`` If you want to prioritize one package over another, you can add version -specifiers to *only* the more important package:: +specifiers to *only* the more important package: + +.. tabs:: + + .. group-tab:: Unix/macOS + + .. code-block:: shell + + python -m pip install package_coffee==0.44.1b0 package_tea + + .. group-tab:: Windows + + .. code-block:: shell - pip install package_coffee==0.44.1b0 package_tea + py -m pip install package_coffee==0.44.1b0 package_tea This will result in: @@ -1325,3 +1678,4 @@ announcements on the `low-traffic packaging announcements list`_ and .. _the official Python blog: https://blog.python.org/ .. _requests: https://requests.readthedocs.io/en/master/user/authentication/#netrc-authentication .. _Python standard library: https://docs.python.org/3/library/netrc.html +.. _Python Windows launcher: https://docs.python.org/3/using/windows.html#launcher diff --git a/docs/pip_sphinxext.py b/docs/pip_sphinxext.py index 6cc7a2c82ec..9386d71e796 100644 --- a/docs/pip_sphinxext.py +++ b/docs/pip_sphinxext.py @@ -15,11 +15,17 @@ class PipCommandUsage(rst.Directive): required_arguments = 1 + optional_arguments = 3 def run(self): cmd = create_command(self.arguments[0]) + cmd_prefix = 'python -m pip' + if len(self.arguments) > 1: + cmd_prefix = " ".join(self.arguments[1:]) + cmd_prefix = cmd_prefix.strip('"') + cmd_prefix = cmd_prefix.strip("'") usage = dedent( - cmd.usage.replace('%prog', 'pip {}'.format(cmd.name)) + cmd.usage.replace('%prog', '{} {}'.format(cmd_prefix, cmd.name)) ).strip() node = nodes.literal_block(usage, usage) return [node] diff --git a/news/7311.doc b/news/7311.doc new file mode 100644 index 00000000000..6ed2c420489 --- /dev/null +++ b/news/7311.doc @@ -0,0 +1 @@ +Add OS tabs for OS-specific commands. diff --git a/tools/requirements/docs.txt b/tools/requirements/docs.txt index 267d5b1ddfb..dc93a60ff3d 100644 --- a/tools/requirements/docs.txt +++ b/tools/requirements/docs.txt @@ -1,6 +1,7 @@ sphinx == 3.2.1 git+https://github.com/python/python-docs-theme.git#egg=python-docs-theme git+https://github.com/pypa/pypa-docs-theme.git#egg=pypa-docs-theme +sphinx-tabs == 1.1.13 # `docs.pipext` uses pip's internals to generate documentation. So, we install # the current directory to make it work.