Install & Compatibility
Where this runs
tested against v0.20.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.811s · 33.5MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.9s · import 0.725s · 34MB
32MB installed
● package 32MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
main
✓ from fawltydeps.main import main
FawltyDeps is primarily a command-line tool. This `main` function is its internal CLI entry point and is generally not intended for direct programmatic use by consumers.
This quickstart demonstrates how to set up a minimal project and then run `fawltydeps` via a Python `subprocess` call to identify undeclared and unused dependencies. It creates dummy `src/app.py` and `requirements.txt` files, runs the tool, and prints its output, then cleans up.
import os
import subprocess
import shutil
# --- Setup a dummy project for demonstration ---
project_dir = "my_fawltydeps_example_project"
os.makedirs(os.path.join(project_dir, "src"), exist_ok=True)
# Create a Python file with imports
with open(os.path.join(project_dir, "src", "app.py"), "w") as f:
f.write("import requests\nimport pandas\nfrom os import path\n")
# Create a requirements file with some declared dependencies
with open(os.path.join(project_dir, "requirements.txt"), "w") as f:
f.write("requests==2.31.0\n")
# --- Run FawltyDeps via subprocess ---
print(f"\nRunning fawltydeps in '{project_dir}' to find mismatches...\n")
try:
# Execute the fawltydeps command line tool
result = subprocess.run(
["fawltydeps", "--verbose", "--code", "src", "--deps", "requirements.txt"],
cwd=project_dir,
capture_output=True,
text=True,
check=False # Set to True if you expect a non-zero exit for issues
)
print("FawltyDeps Output:\n")
print(result.stdout)
if result.stderr:
print("FawltyDeps Errors:\n")
print(result.stderr)
except FileNotFoundError:
print("Error: 'fawltydeps' command not found. Please install it with 'pip install fawltydeps'.")
except Exception as e:
print(f"An unexpected error occurred: {e}")
finally:
# --- Clean up the dummy project ---
if os.path.exists(project_dir):
shutil.rmtree(project_dir)
print(f"\nCleaned up example project directory: '{project_dir}'")
fawltydeps --version
Errors
Common errors & fixes
fawltydeps: command not found
The `fawltydeps` executable is not in your system's PATH, or it was installed in an isolated virtual environment that is not currently active.
fixActivate the virtual environment where `fawltydeps` was installed, or ensure its installation directory is in your PATH. Alternatively, use `python -m fawltydeps`.
ModuleNotFoundError: No module named 'fawltydeps'
FawltyDeps was not installed in the current Python environment where you are trying to run it programmatically or via `python -m`.
fixRun `pip install fawltydeps` in your active Python environment.
FawltyDeps reports a dependency as unused in my Conda/Pixi project, but I know it's needed.
FawltyDeps focuses on Python import statements. It might flag non-Python dependencies (e.g., system libraries, CLI tools) declared in `environment.yml` or `pixi.toml` as unused if they are not directly imported by Python code.
fixThis is often expected behavior for non-Python components. Verify if the dependency is indeed a non-Python package; FawltyDeps' analysis is for Python imports.
FawltyDeps says 'PIL' is undeclared, but I have 'Pillow' installed in my environment.
FawltyDeps v0.20.0+ output distinguishes between the Python import name (e.g., `PIL`) and the PyPI package name (e.g., `Pillow`). You've imported `PIL`, but FawltyDeps is checking for the *package* `Pillow` to be declared.
fixEnsure the correct *package name* (e.g., `Pillow`) is explicitly declared in your dependency files (`requirements.txt`, `pyproject.toml`, etc.). FawltyDeps v0.20.0+ will usually suggest the correct package name.
Upgrade
Version history
0.20.0latest on PyPI · released Jun 5, 2025
Audit
Dependencies
No dependency data recorded yet.