Installation Guide

Learn how to install and configure pip on your system

guide

Python’s package ecosystem is powered by pip, the de‑facto package installer. Whether you’re setting up a new project, managing dependencies, or configuring a build environment, understanding how to install, use, and customize pip is essential. This guide walks through the key steps and best practices, drawing on the official documentation from the Python Packaging Authority and the Python core team.

1. Installing pip

1.1. Pre‑installed on Modern Python Distributions

Python 3.4 and newer ship with pip bundled. Running python -m pip --version will confirm its presence. If you’re using a virtual environment (venv or virtualenv), pip is automatically available inside that environment.

1.2. Installing pip on Systems Without It

If pip is missing, the recommended bootstrap method is the get-pip.py script:

curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
python get-pip.py

This script downloads the latest pip wheel and installs it. It works on Windows, macOS, and Linux. For more details, see the official installation guide: https://pip.pypa.io/en/stable/installation/.

1.3. Using the OS Package Manager

On many Linux distributions, pip can be installed via the system package manager (e.g., apt install python3-pip on Debian/Ubuntu). However, the OS‑provided version may lag behind the latest pip release, so the get-pip.py method is preferred for up‑to‑date features.

2. Basic Usage

2.1. Installing Packages

pip install requests

Pip resolves dependencies, downloads wheels or source distributions, and installs them into the current environment.

2.2. Upgrading Packages

pip install --upgrade requests

2.3. Listing Installed Packages

pip list

For a more detailed view, including package versions and locations, use pip show <package>.

2.4. Freezing Requirements

pip freeze > requirements.txt

This captures the exact versions of all installed packages, ideal for reproducible environments.

3. Configuration

Pip can be configured via command‑line options, environment variables, or configuration files. The reference guide (https://pip.pypa.io/en/stable/reference/pip_config/) details the hierarchy:

  1. Command‑line options – highest precedence.
  2. Environment variables – e.g., PIP_INDEX_URL.
  3. User‑level config file – ~/.config/pip/pip.conf (Linux/macOS) or %APPDATA%\pip\pip.ini (Windows).
  4. Global config file – /etc/pip.conf (Linux) or C:\ProgramData\pip\pip.ini (Windows).

3.1. Common Settings

Setting Purpose Example
index-url Primary PyPI mirror index-url = https://pypi.org/simple
trusted-host Bypass SSL verification for a host trusted-host = pypi.org
cache-dir Location of pip’s cache cache-dir = ~/.cache/pip
timeout Network timeout in seconds timeout = 60

4. Cross‑Platform Considerations

4.1. Windows

  • Use the official Python installer from python.org; it includes pip and adds Python to the PATH.
  • For legacy systems, the Scripts directory (C:\Python39\Scripts) contains pip.exe. Add this to your PATH if you’re using a custom installation.
  • Virtual environments on Windows create a Scripts folder; activate with .\venv\Scripts\activate.

4.2. macOS & Linux

  • The python3 -m pip invocation is preferred to avoid conflicts with system‑installed pip.
  • Virtual environments are created with python3 -m venv env; activate with source env/bin/activate.
  • On Unix, pip’s configuration files reside under ~/.config/pip/.

4.3. Handling Permissions

Installing packages globally (sudo pip install ...) is discouraged because it can interfere with the system Python. Prefer virtual environments or the --user flag:

pip install --user requests

This installs packages into ~/.local/lib/pythonX.Y/site-packages.

5. Advanced Topics

5.1. Building Wheels

Pip can build wheels from source distributions if a wheel is not available:

pip wheel requests

The resulting .whl file can be distributed or installed offline.

5.2. Using a Private Index

For internal packages, set up a private PyPI server (e.g., devpi, Artifactory) and configure pip:

[global]
index-url = https://my.private.repo/simple

5.3. Proxy Support

When behind a corporate proxy:

pip install requests --proxy http://user:pass@proxy.example.com:8080

Or set the HTTP_PROXY/HTTPS_PROXY environment variables.

6. Troubleshooting

Symptom Likely Cause Fix
pip: command not found Python not in PATH Add Python’s Scripts directory to PATH
SSL errors Outdated certificates Update CA certificates or use --trusted-host
Permission denied Installing globally Use virtualenv or --user
Dependency conflicts Incompatible package versions Use pip install --upgrade or pin versions in requirements.txt

7. Resources

By mastering these fundamentals, you’ll be able to set up clean, reproducible Python environments, manage dependencies efficiently, and adapt pip to a wide range of development workflows. Happy coding!