Skip to content

pip and Package Management

Install, upgrade, and manage Python packages with pip, PyPI, and pyproject.toml.

What you'll learn

  • Install and uninstall packages with pip
  • Upgrade, downgrade, and pin package versions
  • Search and inspect packages on PyPI
  • Use pyproject.toml for modern project config
  • Troubleshoot common pip issues

Concept

What Is pip?

pip is the Python package installer. It downloads packages from PyPI (the Python Package Index — over 400,000 packages) and installs them into your environment:

pip install requests          # install latest version
pip install requests==2.31.0  # install specific version
pip install "requests>=2.30"  # install minimum version
pip uninstall requests        # remove a package

pip is included with Python 3.4+ — you do not need to install it separately. It is the standard way to add third-party libraries to your project.

Installing Packages

# Single package
pip install django

# Multiple packages
pip install django requests numpy

# From a requirements file
pip install -r requirements.txt

# With version constraints
pip install "django>=4.2,<5.0"

# From a Git repository
pip install git+https://github.com/user/repo.git

# In editable mode (for local development)
pip install -e .

Version specifiers:

  • ==2.31.0 — exactly this version
  • >=2.31.0 — this version or higher
  • <3.0.0 — less than this version
  • ~=2.31.0 — compatible release (2.31.x)
  • !=2.32.0 — any version except this one

Upgrading and Downgrading

# Upgrade to the latest version
pip install --upgrade requests
# or
pip install -U requests

# Downgrade to a specific version
pip install requests==2.30.0

# Show what would be upgraded without doing it
pip list --outdated

Be careful with upgrades — a new version might have breaking changes. Always check the package's changelog before upgrading in production.

Inspecting Packages

# Show details about an installed package
pip show requests

# List all installed packages
pip list

# Find which packages depend on a given package
pip show requests | grep Requires

# Check a package's files
pip show -f requests

Searching PyPI

# Search PyPI (deprecated in pip 21.2+ — use the website)
pip search "http client"

# Instead, browse https://pypi.org

The pip search command was disabled due to abuse of the XMLRPC API. Browse [pypi.org](https://pypi.org) directly to search for packages.

pyproject.toml — Modern Project Configuration

pyproject.toml is the modern standard for Python project configuration (PEP 518/621). It replaces setup.py and setup.cfg:

[project]
name = "myapp"
version = "1.0.0"
description = "My awesome application"
requires-python = ">=3.10"
dependencies = [
    "django>=4.2",
    "requests>=2.31.0",
]

[project.optional-dependencies]
dev = ["pytest", "black", "mypy"]

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.backends._legacy:_backend"

Install in development mode:

pip install -e ".[dev]"   # install with dev dependencies

Common pip Issues

pip not found — ensure Python is installed and on your PATH. On some systems, use python -m pip instead of pip to ensure you use the right Python's pip.

Permission denied — never use sudo pip install. It can break system tools. Use a virtual environment instead.

SSL certificate errors — on corporate networks, you may need to configure certificates:

pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org requests

Conflicting dependencies — when two packages require incompatible versions of a third. Use pip check to detect conflicts, and consider pip-tools or poetry for better dependency resolution.

Example

              # --- Shell commands for pip ---
# pip install requests
# pip install "django>=4.2,<5.0"
# pip install -r requirements.txt
# pip install -e .
# pip uninstall requests
# pip install --upgrade requests
# pip list
# pip show requests
# pip check  # check for dependency conflicts

# --- pyproject.toml example ---
# [project]
# name = "myapp"
# version = "1.0.0"
# requires-python = ">=3.10"
# dependencies = [
#     "django>=4.2",
#     "requests>=2.31.0",
# ]
# [project.optional-dependencies]
# dev = ["pytest", "black", "mypy"]

# --- Python code: inspect installed packages ---
import importlib
import subprocess
import sys

def check_package(package_name):
    """Check if a package is installed and get its version."""
    try:
        spec = importlib.util.find_spec(package_name)
        if spec is None:
            return f"{package_name}: NOT installed"
        try:
            version = importlib.metadata.version(package_name)
            return f"{package_name}: {version} (installed)"
        except importlib.metadata.PackageNotFoundError:
            return f"{package_name}: installed (version unknown)"
    except Exception as e:
        return f"{package_name}: error - {e}"

# Check common packages
for pkg in ["json", "os", "math", "requests", "numpy", "django"]:
    print(check_package(pkg))

# Show pip version
result = subprocess.run(
    [sys.executable, "-m", "pip", "--version"],
    capture_output=True, text=True
)
print(f"\npip info: {result.stdout.strip()}")
            

Shows pip commands for install/uninstall/upgrade, a pyproject.toml example, and Python code using importlib to check which packages are installed and their versions.

Try it

  • JSON Formatter

    pyproject.toml and package metadata use structured formats.

  • CSV to JSON

    Many pip-installed packages (like pandas) work with CSV and JSON data.

Common mistakes

The mistake

Using sudo pip install which can break system Python tools

The fix

Never use sudo with pip — it installs to the system Python and can break OS tools that depend on it. Always use a virtual environment and install without sudo. If you must install globally, use 'pip install --user'.

The mistake

Not pinning versions and getting different behavior across machines

The fix

Use 'pip freeze > requirements.txt' to record exact versions. Pin with == for reproducible installs. Without pinning, 'pip install -r requirements.txt' may install different versions on different days, causing subtle bugs.

Related Cheatsheets

Look up unfamiliar terms

A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.

View glossary

Build real projects

Apply what you learned by building guided projects with starter code and solutions.

View projects

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors