check-requirements-txt

A tool (and also a pre-commit hook) to automatically check the missing packages in requirements.txt and pyproject.toml.

Table of Contents

• Features
• Installation
• Usage
• Pre-commit Hook
• Output Sample
• License

Features

• ✅ Multiple dependency formats: Supports both requirements.txt and pyproject.toml
• ✅ Modern Python projects: Full support for uv package manager and PEP 735 dependency groups
• ✅ Comprehensive TOML parsing:
  • project.dependencies - Main project dependencies
  • project.optional-dependencies - Optional dependencies/extras
  • dependency-groups - PEP 735 dependency groups with include-group support
  • tool.uv.dev-dependencies - Legacy uv development dependencies
• ✅ Auto-detection: Automatically finds pyproject.toml and requirements.txt files
• ✅ Python 3.10-3.14: Full compatibility across all modern Python versions
• ✅ Pre-commit integration: Works seamlessly as a pre-commit hook
• ✅ Type-safe: Fully typed with pyright/mypy support
• ✅ Unused dependency detection: Find packages in requirements that aren't used in code
• ✅ Parallel processing: Fast multi-file scanning with configurable workers

Installation

Install using pip:

pip install check-requirements-txt

Or using uv:

uv add --dev check-requirements-txt

Usage

Command Line

Check dependencies in your project:

# Auto-detect pyproject.toml or requirements.txt files
check-requirements-txt src/

# Specify a requirements file
check-requirements-txt src/ -r requirements.txt

# Specify a pyproject.toml file
check-requirements-txt src/ -r pyproject.toml

# Check specific Python files
check-requirements-txt main.py utils.py -r pyproject.toml

# Check for unused dependencies
check-requirements-txt --unused src/

# Use parallel processing for faster scanning
check-requirements-txt --parallel --max-workers 8 src/

提示：目录既可以通过位置参数传入（如 check-requirements-txt src/），也可以使用 --dst_dir src/，两者行为一致。

Supported File Formats

pyproject.toml (recommended for modern Python projects):

[project]
dependencies = ["requests>=2.25.0", "packaging"]

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

[dependency-groups]
lint = ["ruff", "mypy"]
test = ["coverage", "pytest-cov"]

[tool.uv]
dev-dependencies = ["pre-commit"]

requirements.txt (traditional format):

requests>=2.25.0
packaging
pytest  # dev dependency

Pre-commit Hook

Set up pre-commit hooks for automatic checking:

See pre-commit for instructions

Sample .pre-commit-config.yaml:

Note: Due to the pre-commit isolated environment, this package can't act as a normal git repo pre-commit hook. If your dependency files don't match the default patterns (*requirement*.txt or pyproject.toml), specify them explicitly.

default_stages: [commit]

repos:
  - repo: local
    hooks:
      - id: check-requirements-txt
        name: check-requirements-txt
        description: Check missing packages in requirements.txt or pyproject.toml
        entry: check-requirements-txt
        args: ['--dst_dir', '.', '--ignore', 'pip,whatever,modules,you,want,to,ignore,with,comma,separated']
        language: python
        types: [python]

For more options, see check-requirements-txt --help.

Output Sample

When missing dependencies are detected:

Bad import detected: "bs4", check your requirements.txt please.
/Users/ferstar/PycharmProjects/xxx_demo/xxx_spider.py:12
Bad import detected: "requests", check your requirements.txt please.
/Users/ferstar/PycharmProjects/xxx_demo/xxx_handler.py:17
"numpy" required by: {'numpy', 'scikit-learn', 'tensorflow', 'pandas'}

# Exit code indicates number of missing dependencies
$ echo $?
2

When using pyproject.toml:

# All dependencies found - no output, exit code 0
$ check-requirements-txt src/ -r pyproject.toml
$ echo $?
0

# Missing dependency detected
$ check-requirements-txt src/ -r pyproject.toml
Bad import detected: "missing_package", check your pyproject.toml please.
/path/to/file.py:5
$ echo $?
1

When checking for unused dependencies:

# Find unused dependencies
$ check-requirements-txt --unused src/
Unused dependencies found in requirements.txt:
  - pytest
  - black
  - unused-package

# Exit code indicates number of issues (missing + unused)
$ echo $?
3

License

check-requirements-txt is distributed under the terms of the MIT license.