Skip to content
Back to top
View this page

# 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.

Linux

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

MacOS

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

Windows

    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

Linux

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

MacOS

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

Windows

    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

Linux

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

MacOS

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

Windows

    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”)

Linux

    $ 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

MacOS

    $ 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

Windows

    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:

Linux

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

MacOS

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

Windows

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

### Upgrade a package

Linux

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

MacOS

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

Windows

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

### Uninstall a package

Linux

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

MacOS

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

Windows

    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.