diff --git a/docs/html/conf.py b/docs/html/conf.py index 2a4387a352a..9e210539e89 100644 --- a/docs/html/conf.py +++ b/docs/html/conf.py @@ -30,7 +30,7 @@ # General information about the project. project = "pip" -copyright = "2008-2020, PyPA" +copyright = "The pip developers" # Find the version and release information. # We have a single source of truth for our version number: pip's __init__.py file. diff --git a/docs/html/getting-started.md b/docs/html/getting-started.md new file mode 100644 index 00000000000..42ac2c93400 --- /dev/null +++ b/docs/html/getting-started.md @@ -0,0 +1,104 @@ +# Getting Started + +To get started with using pip, you should [install Python] on your system. + +[install Python]: https://realpython.com/installing-python/ + +## Ensure you have a working pip + +As a first step, you should check that you have a working Python with pip +installed. This can be done by running the following commands and making +sure that the output looks similar. + +```{pip-cli} +$ python --version +Python 3.N.N +$ pip --version +pip X.Y.Z from ... (python 3.N.N) +``` + +If that worked, congratulations! You have a working pip in your environment. + +If you got output that does not look like the sample above, please read +the {doc}`installation` page. It provides guidance on how to install pip +within a Python environment that doesn't have it. + +## Common tasks + +### Install a package + +```{pip-cli} +$ pip install sampleproject +[...] +Successfully installed sampleproject +``` + +By default, pip will fetch packages from [Python Package Index][PyPI], a +repository of software for the Python programming language where anyone can +upload packages. + +[PyPI]: https://pypi.org/ + +### Install a package from GitHub + +```{pip-cli} +$ pip install git+https://github.com/pypa/sampleproject.git@main +[...] +Successfully installed sampleproject +``` + +See {ref}`VCS Support` for more information about this syntax. + +### Install a package from a distribution file + +pip can install directly from distribution files as well. They come in 2 forms: + +- {term}`source distribution ` (usually shortened to "sdist") +- {term}`wheel distribution ` (usually shortened to "wheel") + +```{pip-cli} +$ pip install sampleproject-1.0.tar.gz +[...] +Successfully installed sampleproject +$ pip install sampleproject-1.0-py3-none-any.whl +[...] +Successfully installed sampleproject +``` + +### Install multiple packages using a requirements file + +Many Python projects use {file}`requirements.txt` files, to specify the +list of packages that need to be installed for the project to run. To install +the packages listed in that file, you can run: + +```{pip-cli} +$ pip install -r requirements.txt +[...] +Successfully installed sampleproject +``` + +### Upgrade a package + +```{pip-cli} +$ pip install --upgrade sampleproject +Uninstalling sampleproject: + [...] +Proceed (y/n)? y +Successfully uninstalled sampleproject +``` + +### Uninstall a package + +```{pip-cli} +$ pip uninstall sampleproject +Uninstalling sampleproject: + [...] +Proceed (y/n)? y +Successfully uninstalled sampleproject +``` + +## Next Steps + +It is recommended to learn about what virtual environments are and how to use +them. This is covered in the ["Installing Packages"](pypug:tutorials/installing-packages) +tutorial on packaging.python.org. diff --git a/docs/html/index.md b/docs/html/index.md index a84c2665d0e..7cf130c4bb6 100644 --- a/docs/html/index.md +++ b/docs/html/index.md @@ -10,8 +10,8 @@ install packages from the [Python Package Index][pypi] and other indexes. ```{toctree} :hidden: -quickstart -installing +getting-started +installation user_guide cli/index ``` @@ -29,7 +29,7 @@ GitHub If you want to learn about how to use pip, check out the following resources: -- [Quickstart](quickstart) +- [Getting Started](getting-started) - [Python Packaging User Guide](https://packaging.python.org) If you find bugs, need help, or want to talk to the developers, use our mailing diff --git a/docs/html/installation.md b/docs/html/installation.md new file mode 100644 index 00000000000..da975727185 --- /dev/null +++ b/docs/html/installation.md @@ -0,0 +1,78 @@ +# Installation + +Usually, pip is automatically installed if you are: + +- working in a + {ref}`virtual environment ` +- using Python downloaded from [python.org](https://www.python.org) +- using Python that has not been modified by a redistributor to remove + {mod}`ensurepip` + +## Supported Methods + +If your Python environment does not have pip installed, there are 2 mechanisms +to install pip supported directly by pip's maintainers: + +- [`ensurepip`](#using-ensurepip) +- [`get-pip.py`](#using-get-pip-py) + +### `ensurepip` + +Python comes with an {mod}`ensurepip` module[^python], which can install pip in +a Python environment. + +```{pip-cli} +$ python -m ensurepip --upgrade +``` + +More details about how {mod}`ensurepip` works and how it can be used, is +available in the standard library documentation. + +### `get-pip.py` + +This is a Python script that uses some bootstrapping logic to install +pip. + +- Download the script, from . +- Open a terminal/command prompt, `cd` to the folder containing the + `get-pip.py` file and run: + + ```{pip-cli} + $ python get-pip.py + ``` + +More details about this script can be found in [pypa/get-pip]'s README. + +[pypa/get-pip]: https://github.com/pypa/get-pip + +## Alternative Methods + +Depending on how you installed Python, there might be other mechanisms +available to you for installing pip such as +{ref}`using Linux package managers `. + +These mechanisms are provided by redistributors of pip, who may have modified +pip to change its behaviour. This has been a frequent source of user confusion, +since it causes a mismatch between documented behaviour in this documentation +and how pip works after those modifications. + +If you face issues when using Python and pip installed using these mechanisms, +it is recommended to request for support from the relevant provider (eg: Linux +distro community, cloud provider support channels, etc). + +## Compatibility + +The current version of pip works on: + +- Windows, Linux and MacOS. +- CPython 3.6, 3.7, 3.8, 3.9 and latest PyPy3. + +pip is tested to work on the latest patch version of the Python interpreter, +for each of the minor versions listed above. Previous patch versions are +supported on a best effort approach. + +pip's maintainers do not provide support for users on older versions of Python, +and these users should request for support from the relevant provider +(eg: Linux distro community, cloud provider support channels, etc). + +[^python]: The `ensurepip` module was added to the Python standard library in Python 3.4. diff --git a/docs/html/installing.rst b/docs/html/installing.rst index 95b21899dc6..e8d86f3441c 100644 --- a/docs/html/installing.rst +++ b/docs/html/installing.rst @@ -1,230 +1,11 @@ -.. _`Installation`: +:orphan: -============ -Installation -============ +.. meta:: -Do I need to install pip? -========================= + :http-equiv=refresh: 3; url=../installation/ -pip is already installed if you are using Python 2 >=2.7.9 or Python 3 >=3.4 -downloaded from `python.org `_ or if you are working -in a :ref:`Virtual Environment ` -created by :ref:`pypug:virtualenv` or :ref:`venv `. Just make sure -to :ref:`upgrade pip `. +This page has moved +=================== -Use the following command to check whether pip is installed: - -.. tab:: Unix/macOS - - .. code-block:: console - - $ python -m pip --version - pip X.Y.Z from .../site-packages/pip (python X.Y) - -.. tab:: Windows - - .. code-block:: console - - C:\> py -m pip --version - pip X.Y.Z from ...\site-packages\pip (python X.Y) - -Using Linux Package Managers -============================ - -.. warning:: - - If you installed Python from a package manager on Linux, you should always - install pip for that Python installation using the same source. - -See `pypug:Installing pip/setuptools/wheel with Linux Package Managers `_ -in the Python Packaging User Guide. - -Here are ways to contact a few Linux package maintainers if you run into -problems: - -* `Deadsnakes PPA `_ -* `Debian Python Team `_ (for general - issues related to ``apt``) -* `Red Hat Bugzilla `_ - -pip developers do not have control over how Linux distributions handle pip -installations, and are unable to provide solutions to related issues in -general. - -Using ensurepip -=============== - -Python >=3.4 can self-bootstrap pip with the built-in -:ref:`ensurepip ` module. Refer to the standard library -documentation for more details. Make sure to :ref:`upgrade pip ` -after ``ensurepip`` installs pip. - -See the `Using Linux Package Managers`_ section if your Python reports -``No module named ensurepip`` on Debian and derived systems (e.g. Ubuntu). - - -.. _`get-pip`: - -Installing with get-pip.py -========================== - -.. warning:: - - Be cautious if you are using a Python install that is managed by your operating - system or another package manager. ``get-pip.py`` does not coordinate with - those tools, and may leave your system in an inconsistent state. - -To manually install pip, securely [1]_ download ``get-pip.py`` by following -this link: `get-pip.py -`_. Alternatively, use ``curl``:: - - curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py - -Then run the following command in the folder where you -have downloaded ``get-pip.py``: - -.. tab:: Unix/macOS - - .. code-block:: shell - - python get-pip.py - -.. tab:: Windows - - .. code-block:: shell - - py get-pip.py - -``get-pip.py`` also installs :ref:`pypug:setuptools` [2]_ and :ref:`pypug:wheel` -if they are not already. :ref:`pypug:setuptools` is required to install -:term:`source distributions `. Both are -required in order to build a :ref:`Wheel cache` (which improves installation -speed), although neither are required to install pre-built :term:`wheels -`. - -.. note:: - - The get-pip.py script is supported on the same python version as pip. - For the now unsupported Python 2.6, alternate script is available - `here `__. - - -get-pip.py options ------------------- - -.. option:: --no-setuptools - - If set, do not attempt to install :ref:`pypug:setuptools` - -.. option:: --no-wheel - - If set, do not attempt to install :ref:`pypug:wheel` - - -``get-pip.py`` allows :ref:`pip install options ` and the :ref:`general options `. Below are -some examples: - -Install from local copies of pip and setuptools: - -.. tab:: Unix/macOS - - .. code-block:: shell - - python get-pip.py --no-index --find-links=/local/copies - -.. tab:: Windows - - .. code-block:: shell - - py get-pip.py --no-index --find-links=/local/copies - -Install to the user site [3]_: - -.. tab:: Unix/macOS - - .. code-block:: shell - - python get-pip.py --user - -.. tab:: Windows - - .. code-block:: shell - - py get-pip.py --user - -Install behind a proxy: - -.. tab:: Unix/macOS - - .. code-block:: shell - - python get-pip.py --proxy="http://[user:passwd@]proxy.server:port" - -.. tab:: Windows - - .. code-block:: shell - - py get-pip.py --proxy="http://[user:passwd@]proxy.server:port" - -``get-pip.py`` can also be used to install a specified combination of ``pip``, -``setuptools``, and ``wheel`` using the same requirements syntax as pip: - -.. tab:: Unix/macOS - - .. code-block:: shell - - python get-pip.py pip==9.0.2 wheel==0.30.0 setuptools==28.8.0 - -.. tab:: Windows - - .. code-block:: shell - - py get-pip.py pip==9.0.2 wheel==0.30.0 setuptools==28.8.0 - -.. _`Upgrading pip`: - -Upgrading pip -============= - -.. tab:: Unix/macOS - - .. code-block:: shell - - python -m pip install -U pip - -.. tab:: Windows - - .. code-block:: shell - - py -m pip install -U pip - - -.. _compatibility-requirements: - -Python and OS Compatibility -=========================== - -pip works with CPython versions 3.6, 3.7, 3.8, 3.9 and also PyPy. - -This means pip works on the latest patch version of each of these minor -versions. Previous patch versions are supported on a best effort approach. - -pip works on Unix/Linux, macOS, and Windows. - - ----- - -.. [1] "Secure" in this context means using a modern browser or a - tool like ``curl`` that verifies SSL certificates when downloading from - https URLs. - -.. [2] Beginning with pip v1.5.1, ``get-pip.py`` stopped requiring setuptools to - be installed first. - -.. [3] The pip developers are considering making ``--user`` the default for all - installs, including ``get-pip.py`` installs of pip, but at this time, - ``--user`` installs for pip itself, should not be considered to be fully - tested or endorsed. For discussion, see `Issue 1668 - `_. +You should be redirected automatically in 3 seconds. If that didn't +work, here's a link: :doc:`installation` diff --git a/docs/html/quickstart.rst b/docs/html/quickstart.rst index 96602a7b316..4385f4a7394 100644 --- a/docs/html/quickstart.rst +++ b/docs/html/quickstart.rst @@ -1,136 +1,11 @@ -========== -Quickstart -========== +:orphan: -First, :doc:`install pip `. +.. meta:: -Install a package from `PyPI`_: + :http-equiv=refresh: 3; url=../getting-started/ -.. tab:: Unix/macOS +This page has moved +=================== - .. code-block:: console - - $ python -m pip install SomePackage - [...] - Successfully installed SomePackage - -.. tab:: Windows - - .. code-block:: console - - C:\> py -m pip install SomePackage - [...] - Successfully installed SomePackage - - -Install a package that's already been downloaded from `PyPI`_ or -obtained from elsewhere. This is useful if the target machine does not have a -network connection: - -.. tab:: Unix/macOS - - .. code-block:: console - - $ python -m pip install SomePackage-1.0-py2.py3-none-any.whl - [...] - Successfully installed SomePackage - -.. tab:: Windows - - .. code-block:: console - - C:\> py -m pip install SomePackage-1.0-py2.py3-none-any.whl - [...] - Successfully installed SomePackage - -Show what files were installed: - -.. tab:: Unix/macOS - - .. code-block:: console - - $ python -m pip show --files SomePackage - Name: SomePackage - Version: 1.0 - Location: /my/env/lib/pythonx.x/site-packages - Files: - ../somepackage/__init__.py - [...] - -.. tab:: Windows - - .. code-block:: console - - C:\> py -m pip show --files SomePackage - Name: SomePackage - Version: 1.0 - Location: /my/env/lib/pythonx.x/site-packages - Files: - ../somepackage/__init__.py - [...] - -List what packages are outdated: - -.. tab:: Unix/macOS - - .. code-block:: console - - $ python -m pip list --outdated - SomePackage (Current: 1.0 Latest: 2.0) - -.. tab:: Windows - - .. code-block:: console - - C:\> py -m pip list --outdated - SomePackage (Current: 1.0 Latest: 2.0) - -Upgrade a package: - -.. tab:: Unix/macOS - - .. code-block:: console - - $ python -m pip install --upgrade SomePackage - [...] - Found existing installation: SomePackage 1.0 - Uninstalling SomePackage: - Successfully uninstalled SomePackage - Running setup.py install for SomePackage - Successfully installed SomePackage - -.. tab:: Windows - - .. code-block:: console - - C:\> py -m pip install --upgrade SomePackage - [...] - Found existing installation: SomePackage 1.0 - Uninstalling SomePackage: - Successfully uninstalled SomePackage - Running setup.py install for SomePackage - Successfully installed SomePackage - -Uninstall a package: - -.. tab:: Unix/macOS - - .. code-block:: console - - $ python -m pip uninstall SomePackage - Uninstalling SomePackage: - /my/env/lib/pythonx.x/site-packages/somepackage - Proceed (y/n)? y - Successfully uninstalled SomePackage - -.. tab:: Windows - - .. code-block:: console - - C:\> py -m pip uninstall SomePackage - Uninstalling SomePackage: - /my/env/lib/pythonx.x/site-packages/somepackage - Proceed (y/n)? y - Successfully uninstalled SomePackage - -.. _PyPI: https://pypi.org/ +You should be redirected automatically in 3 seconds. If that didn't +work, here's a link: :doc:`getting-started`