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 Resources
Related Cheatsheets
- Python Cheatsheet
pip commands, version specifiers, and pyproject.toml syntax.
Look up unfamiliar terms
A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.
Build real projects
Apply what you learned by building guided projects with starter code and solutions.
Decode error messages
Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.