Getting Started

To get started with using pip, you should install Python on your system.

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.

$ python --version
Python 3.N.N
$ python -m pip --version
pip X.Y.Z from ... (python 3.N.N)

$ python --version
Python 3.N.N
$ python -m pip --version
pip X.Y.Z from ... (python 3.N.N)

C:> py --version
Python 3.N.N
C:> py -m 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 Installation page. It provides guidance on how to install pip within a Python environment that doesn’t have it.

Common tasks

Install a package

$ python -m pip install sampleproject
[...]
Successfully installed sampleproject

$ python -m pip install sampleproject
[...]
Successfully installed sampleproject

C:> py -m pip install sampleproject
[...]
Successfully installed sampleproject

By default, pip will fetch packages from Python Package Index, a repository of software for the Python programming language where anyone can upload packages.

Install a package from GitHub

$ python -m pip install git+https://github.com/pypa/sampleproject.git@main
[...]
Successfully installed sampleproject

$ python -m pip install git+https://github.com/pypa/sampleproject.git@main
[...]
Successfully installed sampleproject

C:> py -m pip install git+https://github.com/pypa/sampleproject.git@main
[...]
Successfully installed sampleproject

See 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:

  • source distribution (usually shortened to “sdist”)

  • wheel distribution (usually shortened to “wheel”)

$ python -m pip install sampleproject-1.0.tar.gz
[...]
Successfully installed sampleproject
$ python -m pip install sampleproject-1.0-py3-none-any.whl
[...]
Successfully installed sampleproject

$ python -m pip install sampleproject-1.0.tar.gz
[...]
Successfully installed sampleproject
$ python -m pip install sampleproject-1.0-py3-none-any.whl
[...]
Successfully installed sampleproject

C:> py -m pip install sampleproject-1.0.tar.gz
[...]
Successfully installed sampleproject
C:> py -m pip install sampleproject-1.0-py3-none-any.whl
[...]
Successfully installed sampleproject

Install multiple packages using a requirements file

Many Python projects use 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:

$ python -m pip install -r requirements.txt
[...]
Successfully installed sampleproject

$ python -m pip install -r requirements.txt
[...]
Successfully installed sampleproject

C:> py -m pip install -r requirements.txt
[...]
Successfully installed sampleproject

Upgrade a package

$ python -m pip install --upgrade sampleproject
   [...]
Successfully installed sampleproject

$ python -m pip install --upgrade sampleproject
   [...]
Successfully installed sampleproject

C:> py -m pip install --upgrade sampleproject
   [...]
Successfully installed sampleproject

Uninstall a package

$ python -m pip uninstall sampleproject
Uninstalling sampleproject:
   [...]
Proceed (Y/n)? y
Successfully uninstalled sampleproject

$ python -m pip uninstall sampleproject
Uninstalling sampleproject:
   [...]
Proceed (Y/n)? y
Successfully uninstalled sampleproject

C:> py -m 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 tutorial on packaging.python.org.