Skip to content

Commit 0a49dd9

Browse files
pradyunsgpradyunsg
authored
Merge pull request #10009 from pradyunsg/new-getting-started-and-installation
2 parents e2f359a + f9dc946 commit 0a49dd9

File tree

6 files changed

+200
-362
lines changed

6 files changed

+200
-362
lines changed

‎docs/html/conf.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@
3030

3131
# General information about the project.
3232
project = "pip"
33-
copyright = "2008-2020, PyPA"
33+
copyright = "The pip developers"
3434

3535
# Find the version and release information.
3636
# We have a single source of truth for our version number: pip's __init__.py file.

‎docs/html/getting-started.md

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# Getting Started
2+
3+
To get started with using pip, you should [install Python] on your system.
4+
5+
[install Python]: https://realpython.com/installing-python/
6+
7+
## Ensure you have a working pip
8+
9+
As a first step, you should check that you have a working Python with pip
10+
installed. This can be done by running the following commands and making
11+
sure that the output looks similar.
12+
13+
```{pip-cli}
14+
$ python --version
15+
Python 3.N.N
16+
$ pip --version
17+
pip X.Y.Z from ... (python 3.N.N)
18+
```
19+
20+
If that worked, congratulations! You have a working pip in your environment.
21+
22+
If you got output that does not look like the sample above, please read
23+
the {doc}`installation` page. It provides guidance on how to install pip
24+
within a Python environment that doesn't have it.
25+
26+
## Common tasks
27+
28+
### Install a package
29+
30+
```{pip-cli}
31+
$ pip install sampleproject
32+
[...]
33+
Successfully installed sampleproject
34+
```
35+
36+
By default, pip will fetch packages from [Python Package Index][PyPI], a
37+
repository of software for the Python programming language where anyone can
38+
upload packages.
39+
40+
[PyPI]: https://pypi.org/
41+
42+
### Install a package from GitHub
43+
44+
```{pip-cli}
45+
$ pip install git+https://github.com/pypa/sampleproject.git@main
46+
[...]
47+
Successfully installed sampleproject
48+
```
49+
50+
See {ref}`VCS Support` for more information about this syntax.
51+
52+
### Install a package from a distribution file
53+
54+
pip can install directly from distribution files as well. They come in 2 forms:
55+
56+
- {term}`source distribution <Source Distribution (or "sdist")>` (usually shortened to "sdist")
57+
- {term}`wheel distribution <Wheel>` (usually shortened to "wheel")
58+
59+
```{pip-cli}
60+
$ pip install sampleproject-1.0.tar.gz
61+
[...]
62+
Successfully installed sampleproject
63+
$ pip install sampleproject-1.0-py3-none-any.whl
64+
[...]
65+
Successfully installed sampleproject
66+
```
67+
68+
### Install multiple packages using a requirements file
69+
70+
Many Python projects use {file}`requirements.txt` files, to specify the
71+
list of packages that need to be installed for the project to run. To install
72+
the packages listed in that file, you can run:
73+
74+
```{pip-cli}
75+
$ pip install -r requirements.txt
76+
[...]
77+
Successfully installed sampleproject
78+
```
79+
80+
### Upgrade a package
81+
82+
```{pip-cli}
83+
$ pip install --upgrade sampleproject
84+
Uninstalling sampleproject:
85+
[...]
86+
Proceed (y/n)? y
87+
Successfully uninstalled sampleproject
88+
```
89+
90+
### Uninstall a package
91+
92+
```{pip-cli}
93+
$ pip uninstall sampleproject
94+
Uninstalling sampleproject:
95+
[...]
96+
Proceed (y/n)? y
97+
Successfully uninstalled sampleproject
98+
```
99+
100+
## Next Steps
101+
102+
It is recommended to learn about what virtual environments are and how to use
103+
them. This is covered in the ["Installing Packages"](pypug:tutorials/installing-packages)
104+
tutorial on packaging.python.org.

‎docs/html/index.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,8 @@ install packages from the [Python Package Index][pypi] and other indexes.
1010
```{toctree}
1111
:hidden:
1212
13-
quickstart
14-
installing
13+
getting-started
14+
installation
1515
user_guide
1616
cli/index
1717
```
@@ -29,7 +29,7 @@ GitHub <https://github.com/pypa/pip>
2929

3030
If you want to learn about how to use pip, check out the following resources:
3131

32-
- [Quickstart](quickstart)
32+
- [Getting Started](getting-started)
3333
- [Python Packaging User Guide](https://packaging.python.org)
3434

3535
If you find bugs, need help, or want to talk to the developers, use our mailing

‎docs/html/installation.md

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Installation
2+
3+
Usually, pip is automatically installed if you are:
4+
5+
- working in a
6+
{ref}`virtual environment <pypug:Creating and using Virtual Environments>`
7+
- using Python downloaded from [python.org](https://www.python.org)
8+
- using Python that has not been modified by a redistributor to remove
9+
{mod}`ensurepip`
10+
11+
## Supported Methods
12+
13+
If your Python environment does not have pip installed, there are 2 mechanisms
14+
to install pip supported directly by pip's maintainers:
15+
16+
- [`ensurepip`](#using-ensurepip)
17+
- [`get-pip.py`](#using-get-pip-py)
18+
19+
### `ensurepip`
20+
21+
Python comes with an {mod}`ensurepip` module[^python], which can install pip in
22+
a Python environment.
23+
24+
```{pip-cli}
25+
$ python -m ensurepip --upgrade
26+
```
27+
28+
More details about how {mod}`ensurepip` works and how it can be used, is
29+
available in the standard library documentation.
30+
31+
### `get-pip.py`
32+
33+
This is a Python script that uses some bootstrapping logic to install
34+
pip.
35+
36+
- Download the script, from <https://bootstrap.pypa.io/get-pip.py>.
37+
- Open a terminal/command prompt, `cd` to the folder containing the
38+
`get-pip.py` file and run:
39+
40+
```{pip-cli}
41+
$ python get-pip.py
42+
```
43+
44+
More details about this script can be found in [pypa/get-pip]'s README.
45+
46+
[pypa/get-pip]: https://github.com/pypa/get-pip
47+
48+
## Alternative Methods
49+
50+
Depending on how you installed Python, there might be other mechanisms
51+
available to you for installing pip such as
52+
{ref}`using Linux package managers <pypug:installing pip/setuptools/wheel with linux package managers>`.
53+
54+
These mechanisms are provided by redistributors of pip, who may have modified
55+
pip to change its behaviour. This has been a frequent source of user confusion,
56+
since it causes a mismatch between documented behaviour in this documentation
57+
and how pip works after those modifications.
58+
59+
If you face issues when using Python and pip installed using these mechanisms,
60+
it is recommended to request for support from the relevant provider (eg: Linux
61+
distro community, cloud provider support channels, etc).
62+
63+
## Compatibility
64+
65+
The current version of pip works on:
66+
67+
- Windows, Linux and MacOS.
68+
- CPython 3.6, 3.7, 3.8, 3.9 and latest PyPy3.
69+
70+
pip is tested to work on the latest patch version of the Python interpreter,
71+
for each of the minor versions listed above. Previous patch versions are
72+
supported on a best effort approach.
73+
74+
pip's maintainers do not provide support for users on older versions of Python,
75+
and these users should request for support from the relevant provider
76+
(eg: Linux distro community, cloud provider support channels, etc).
77+
78+
[^python]: The `ensurepip` module was added to the Python standard library in Python 3.4.

0 commit comments

Comments
 (0)