Deptry Dependency Checker

Common errors

• deptry not working virtualenv / deptry ModuleNotFoundError

  cause Deptry needs to be installed within the project's virtual environment to properly access the metadata of the installed packages. Installing it globally prevents it from seeing project-specific dependencies.
  fix Activate your project's virtual environment, then install deptry using `pip install deptry`, `poetry add --group dev deptry`, or `uv add --dev deptry`.

• DEP001 'some_module' imported but missing from the dependency definitions

  cause This error occurs when a module is imported in your code but is not explicitly listed as a direct dependency in your `pyproject.toml` or `requirements.txt` file, or if it's a first-party module not recognized by deptry.
  fix Add the corresponding package as a direct dependency to your `pyproject.toml` or `requirements.txt`. If it's a first-party module, configure `deptry` to recognize it using `known_first_party` in your `pyproject.toml` (e.g., `[tool.deptry] known_first_party = ['your_local_module']`).

• DEP002 'some_package' defined as a dependency but not used in the codebase

  cause This warning indicates that a dependency is listed in your project's manifest but deptry doesn't detect any imports from it within your codebase, or it's a development dependency being scanned incorrectly.
  fix If the dependency is genuinely unused, remove it from your project's dependencies. If it is used in a way deptry doesn't detect (e.g., dynamic imports, CLI tools), you can ignore the specific rule for that package (`deptry --per-rule-ignores DEP002=some_package`) or exclude relevant files/directories (`deptry --exclude 'path/to/files/*'`). Ensure development dependencies are correctly categorized.

• DEP003 'some_transitive_module' imported but it is a transitive dependency

  cause This warning occurs when your code directly imports a module whose parent package is not a direct dependency, but rather a dependency of another package listed in your project's direct dependencies.
  fix Add the `some_transitive_module`'s corresponding package as a direct dependency to your `pyproject.toml` or `requirements.txt` to explicitly declare its usage. Alternatively, you can ignore this specific violation using `--ignore DEP003` or `--per-rule-ignores DEP003=some_transitive_package` if you understand and accept the implications.

Warnings

• breaking Deptry's ownership and repository moved from `s-weigand/deptry` to `astral-sh/deptry`. While the core CLI interface largely remained consistent, ensure you are installing the package from the official source and referring to the documentation at `deptry.astral.sh`. Older guides or references might point to the archived repository.
  Fix: Verify your `pip install` command (it should be `pip install deptry`) and documentation sources. The current official `deptry` is maintained by Astral.
• breaking The `--requirements-txt` CLI flag was removed. Deptry now relies on auto-discovery of dependency files (e.g., `requirements.txt`, `pyproject.toml`) or explicit configuration within `pyproject.toml`.
  Fix: Remove the `--requirements-txt` flag from your commands. Deptry will automatically detect common dependency files. For explicit control, configure `dependency_file_paths` in `[tool.deptry]` within your `pyproject.toml`.
• gotcha Deptry may sometimes report false positives (unused dependencies) or false negatives (missing dependencies). This can occur due to dynamic imports, specific project structures, or dependencies used only in non-source files (e.g., configurations, CI scripts).
  Fix: Configure `ignore_unused`, `ignore_missing`, `ignore_transitive`, and `exclude` paths in your `pyproject.toml` under `[tool.deptry]` to fine-tune the analysis for your project's specific needs. Use comments to explain ignores for future maintainers.
• gotcha Deptry requires Python 3.10 or newer. Attempting to run it with older Python versions will result in an installation error or runtime failures.
  Fix: Ensure your project's Python environment and the environment where Deptry is installed is 3.10 or higher. Upgrade Python if necessary.

Install

• pip install deptry Install Deptry

Quickstart

Run Deptry on the current directory to check for dependency issues. This will scan source files and project configuration to identify unused, missing, or transitive dependencies. Configure via `pyproject.toml` for more specific checks.

deptry .