{"id":8987,"library":"fawltydeps","title":"FawltyDeps","description":"FawltyDeps is a command-line tool designed to find undeclared and unused third-party dependencies in Python projects. It analyzes Python code for import statements and compares them against declared dependencies in `pyproject.toml`, `requirements.txt`, `environment.yml`, and `pixi.toml` files. The current version is 0.20.0, with a release cadence of roughly once a month for minor versions.","status":"active","version":"0.20.0","language":"en","source_language":"en","source_url":"https://github.com/tweag/FawltyDeps","tags":["dependency analysis","static analysis","linter","tool","project management","cli"],"install":[{"cmd":"pip install fawltydeps","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"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.","symbol":"main","correct":"from fawltydeps.main import main"}],"quickstart":{"code":"import os\nimport subprocess\nimport shutil\n\n# --- Setup a dummy project for demonstration ---\nproject_dir = \"my_fawltydeps_example_project\"\nos.makedirs(os.path.join(project_dir, \"src\"), exist_ok=True)\n\n# Create a Python file with imports\nwith open(os.path.join(project_dir, \"src\", \"app.py\"), \"w\") as f:\n    f.write(\"import requests\\nimport pandas\\nfrom os import path\\n\")\n\n# Create a requirements file with some declared dependencies\nwith open(os.path.join(project_dir, \"requirements.txt\"), \"w\") as f:\n    f.write(\"requests==2.31.0\\n\")\n\n# --- Run FawltyDeps via subprocess ---\nprint(f\"\\nRunning fawltydeps in '{project_dir}' to find mismatches...\\n\")\ntry:\n    # Execute the fawltydeps command line tool\n    result = subprocess.run(\n        [\"fawltydeps\", \"--verbose\", \"--code\", \"src\", \"--deps\", \"requirements.txt\"],\n        cwd=project_dir,\n        capture_output=True,\n        text=True,\n        check=False # Set to True if you expect a non-zero exit for issues\n    )\n    print(\"FawltyDeps Output:\\n\")\n    print(result.stdout)\n    if result.stderr:\n        print(\"FawltyDeps Errors:\\n\")\n        print(result.stderr)\nexcept FileNotFoundError:\n    print(\"Error: 'fawltydeps' command not found. Please install it with 'pip install fawltydeps'.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\nfinally:\n    # --- Clean up the dummy project ---\n    if os.path.exists(project_dir):\n        shutil.rmtree(project_dir)\n        print(f\"\\nCleaned up example project directory: '{project_dir}'\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Manually verify such dependencies; they are correctly declared but not directly imported by Python code and are thus expected to appear as unused by FawltyDeps.","message":"When analyzing Conda or Pixi projects (v0.18.0+), FawltyDeps might report non-Python dependencies (e.g., system libraries, CLI tools) as 'unused'.","severity":"gotcha","affected_versions":"0.18.0+"},{"fix":"Always consult the suggested package name provided by FawltyDeps, especially when addressing undeclared dependencies. Ensure the *package name* is declared.","message":"FawltyDeps (v0.20.0+) now distinguishes between Python import names (e.g., `PIL`) and PyPI package names (e.g., `Pillow`) in its output, and will suggest package names for undeclared dependencies.","severity":"gotcha","affected_versions":"0.20.0+"},{"fix":"Upgrade to v0.13.3 or newer for improved and more reliable Python environment detection logic.","message":"Older versions of FawltyDeps (pre-0.13.3) had different logic for discovering Python environments, which could lead to incorrect dependency resolution, especially regarding the current environment or multiple environments.","severity":"deprecated","affected_versions":"<0.13.3"},{"fix":"For optimal performance, ensure `uv` is installed (`pip install uv`). If `uv` is not found, FawltyDeps will fall back to using `pip`, which may be slower.","message":"The `--install-deps` option (v0.17.0+) for creating temporary virtual environments now uses `uv` by default if installed, leading to significantly faster operations compared to `pip`.","severity":"gotcha","affected_versions":"0.17.0+"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Activate the virtual environment where `fawltydeps` was installed, or ensure its installation directory is in your PATH. Alternatively, use `python -m fawltydeps`.","cause":"The `fawltydeps` executable is not in your system's PATH, or it was installed in an isolated virtual environment that is not currently active.","error":"fawltydeps: command not found"},{"fix":"Run `pip install fawltydeps` in your active Python environment.","cause":"FawltyDeps was not installed in the current Python environment where you are trying to run it programmatically or via `python -m`.","error":"ModuleNotFoundError: No module named 'fawltydeps'"},{"fix":"This is often expected behavior for non-Python components. Verify if the dependency is indeed a non-Python package; FawltyDeps' analysis is for Python imports.","cause":"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.","error":"FawltyDeps reports a dependency as unused in my Conda/Pixi project, but I know it's needed."},{"fix":"Ensure 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.","cause":"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.","error":"FawltyDeps says 'PIL' is undeclared, but I have 'Pillow' installed in my environment."}]}