Your company here — click to reach over 10,000 unique daily visitors

fawltydeps - Man Page

manual page for FawltyDeps v0.16.0


usage: fawltydeps

[--check | --check-undeclared | --check-unused | --list-sources | --list-imports | --list-deps] [--summary | --detailed | --json] [--code PATH_OR_STDIN [PATH_OR_STDIN ...]] [--deps PATH [PATH ...]] [--deps-parser-choice {requirements.txt,setup.py,setup.cfg,pyproject.toml}] [--pyenv PYENV_DIR [PYENV_DIR ...]] [--exclude PATTERN [PATTERN ...]] [--exclude-from PATH [PATH ...]] [--install-deps] [--custom-mapping-file FILE_PATH [FILE_PATH ...]] [--config-file CONFIG_FILE] [--ignore-undeclared IMPORT_NAME [IMPORT_NAME ...]] [--ignore-unused DEP_NAME [DEP_NAME ...]] [-v] [-q] [--generate-toml-config] [-V] [-h] [basepaths ...]

Find undeclared and/or unused 3rd-party dependencies in your Python project.

Supports finding 3rd-party imports in Python scripts (*.py) and Jupyter notebooks (*.ipynb).

Supports finding dependency declarations in *requirements*.txt (and .in) files, pyproject.toml (following PEP 621 or Poetry conventions), setup.cfg, as well as limited support for setup.py files with a single, simple setup() call and minimal computation involved in setting the install_requires and extras_require arguments.

Actions (choose one)


Report both undeclared and unused dependencies (default)


Report only undeclared dependencies


Report only unused dependencies


List input paths used to extract imports, declared dependencies and find installed packages


List third-party imports extracted from code


List declared dependencies

Output format (choose one)


Generate human-readable summary report (default)


Generate human-readable detailed report


Generate JSON output instead of a human-readable report

Source paths options


Optional directories in which to search for code (imports), dependency declarations and/or Python environments. Defaults to the current directory.


Code to parse for import statements (files or directories, or use '-' to read code from stdin). Defaults to basepaths (see above).

--deps PATH [PATH ...]

Where to find dependency declarations (files or directories). Defaults to finding supported files under basepaths (see above).

--deps-parser-choice {requirements.txt,setup.py,setup.cfg,pyproject.toml}

Name of the parsing strategy to use for dependency declarations, useful for when the file to parse doesn't match a standard name

--pyenv PYENV_DIR [PYENV_DIR ...]

Where to search for Python environments that have project dependencies installed. Defaults to searching under basepaths (see above).

--exclude PATTERN [PATTERN ...]

Exclude patterns (.gitignore format) to apply when looking for code (imports), dependency declarations and/or Python environments. Defaults to '.*', meaning that hidden/dot paths are excluded.

--exclude-from PATH [PATH ...]

Files containing exclude patterns to apply when looking for code (imports), dependency declarations and/or Python environments.


Allow FawltyDeps to `pip install` declared dependencies into a separate temporary virtualenv to discover the imports they expose.

--custom-mapping-file FILE_PATH [FILE_PATH ...]

Path to toml file containing mapping of dependencies to imports defined by the user.

Configuration options

--config-file CONFIG_FILE

Where to find FawltyDeps config (default: ./pyproject.toml)

--ignore-undeclared IMPORT_NAME [IMPORT_NAME ...]

Imports to ignore when looking for undeclared dependencies, e.g. --ignore-undeclared isort pkg_resources

--ignore-unused DEP_NAME [DEP_NAME ...]

Specify a list of dependencies to ignore when looking for unused dependencies. By default, this list includes common development tools. Use this option to customize the list, e.g. --ignore-unused pylint black some_other_module

-v,  --verbose

Increase log level (WARNING by default, -v: INFO, -vv: DEBUG)

-q,  --quiet

Decrease log level (WARNING by default, -q: ERROR, -qq: FATAL)

Other options


Print a TOML config section with the current settings, and exit

-V,  --version

Print the version number of FawltyDeps

-h,  --help

Show this help message and exit


June 2024 FawltyDeps v0.16.0