pipreqs — Generate Python Requirements from Imports

Introduction

pipreqs solves the problem of bloated requirements files by analyzing actual import statements in your Python source code. Unlike pip freeze, which dumps every installed package, pipreqs produces a clean list of only the dependencies your project needs, making requirements files accurate and portable.

What pipreqs Does

• Scans Python files recursively for import and from-import statements
• Maps import names to their corresponding PyPI package names
• Queries PyPI for the latest version of each discovered dependency
• Outputs a minimal requirements.txt with only directly used packages
• Supports custom import-to-package mappings for non-standard package names

Architecture Overview

pipreqs walks the directory tree looking for .py files, extracts import statements using AST parsing, and filters out standard library modules. It then maps module names to PyPI package names using a built-in mapping table. For each identified package, it queries PyPI to determine the installed or latest version. The result is a requirements.txt that reflects what the code actually imports rather than the full environment state.

Self-Hosting & Configuration

• Install via pip or pipx for isolated command-line use
• Point pipreqs at your project root directory to scan all Python files
• Use --ignore to exclude directories like tests, docs, or virtual environments
• Add --diff to compare generated requirements against an existing file
• Use --savepath to write output to a custom file location

Key Features

• Import-based scanning produces minimal, accurate dependency lists
• Built-in mapping of import names to PyPI package names handles common mismatches
• Supports scanning Jupyter notebooks alongside regular Python files
• Ignore patterns let you exclude test fixtures and example scripts
• Diff mode helps review changes before overwriting existing requirements

Comparison with Similar Tools

• pip freeze — Dumps the entire virtualenv; includes unrelated packages and misses project context
• pigar — Similar import-scanning approach; pipreqs has a larger mapping database
• pip-tools — Compiles and pins from abstract specs; complementary, not a replacement for discovery
• Poetry / PDM — Full project managers that track deps via pyproject.toml; more setup required
• deptry — Finds unused or missing dependencies; audits rather than generates requirements files

FAQ

Q: Does pipreqs detect transitive dependencies? A: No. pipreqs lists only direct imports. Use pip-tools or a lock file tool to resolve the full dependency tree.

Q: How does pipreqs handle imports that differ from the package name? A: It uses a built-in mapping table. For custom packages, use the --mapping flag or add entries to the mapping file.

Q: Can pipreqs scan Jupyter notebooks? A: Yes. pipreqs extracts imports from .ipynb files by parsing the code cells.

Q: What if a package is not on PyPI? A: pipreqs skips packages it cannot find on PyPI. You can add them manually to the output file afterward.

Sources

• https://github.com/bndr/pipreqs
• https://pypi.org/project/pipreqs/