deptry checks unused and missing Python dependencies

Why deptry inspects Python imports and declarations

deptry addresses dependency drift in Python projects. A source file can import a package that is absent from the project's dependency definitions, while a declared package can remain after its last import has disappeared. A declaration can also be placed in the wrong dependency group. These mismatches affect installation, CI environments, and the work required to reproduce a build.

The project targets developers who manage Python dependencies through Poetry, pip, PDM, uv, or a PEP 621-compatible declaration format. That range is useful because teams may change package tools while retaining similar source code and project metadata. deptry is intended to inspect those declarations rather than serve as a general Python import sorter or package manager.

Its central operation is static. According to the README, deptry scans Python files in a directory and its subdirectories, collects imported modules, and compares them with the project's listed dependencies. The repository's `justfile` shows the tool being used after `pre-commit` in a `check` recipe, indicating a quality-control role rather than an application runtime role.

This distinction matters. Import-based analysis can produce consistent findings across developers, but it only sees relationships represented by the supported parser and the configured project layout. An import hidden behind dynamic construction, a package loaded by a plugin system, or a dependency used during packaging may require additional project-specific context.

How deptry reports dependency inconsistencies

The README's sample output demonstrates three kinds of findings. `DEP004` reports `numpy` as imported but declared only as a development dependency. `DEP001` reports `matplotlib` as imported while missing from the dependency definitions. `DEP002` reports `pandas` as defined but unused in the codebase. Findings include a file location when deptry can associate the issue with source code.

This comparison model supports both directions of dependency drift. Scanning declarations against imports can identify packages that appear unused. Scanning imports against declarations can identify missing packages and declarations in the wrong dependency group. The README does not explain every issue code or all classification rules, so the complete rule reference should be consulted before treating a specific code as a universal policy.

The repository also contains a Rust crate named `deptryrs`. Its `Cargo.toml` defines a `cdylib` and depends on `pyo3` with the `abi3-py310` feature. It also uses `ruff_python_parser`, `ruff_source_file`, `rayon`, `regex`, and other Rust crates. These files show that the project includes a native Rust component, but they do not fully document the processing boundary between Python and Rust.

Based on the repository layout, deptry should be understood as a static analyzer rather than a runtime tracer. The README does not say that it imports the target application or follows dependencies during execution. A reported import relationship is therefore evidence found through source analysis, not proof that every possible runtime execution path has been observed.

Installing deptry with uv, Poetry, or pip

Install deptry using the package manager already responsible for the target project. The README gives three installation commands. For a uv-managed project, add it to the development dependency group:

uv add --dev deptry

For a Poetry project, use the corresponding development dependency command:

poetry add --dev deptry

For a pip-managed project, install deptry in the project's virtual environment:

pip install deptry

The pip installation deserves particular attention. The README warns that installing deptry globally will not work because deptry needs access to package metadata in the virtual environment. It also says to run deptry from the project root and to use a dedicated virtual environment.

After installation, perform the first scan with the documented root-directory command:

deptry .

The README's sample output starts with a scanned file count and ends with the total number of dependency issues. A real first scan will vary according to the target repository's imports and declarations. Review the command from the same root used for the project's dependency file so that deptry can identify the intended project metadata.

Configuring deptry for dependency groups and exceptions

deptry supports command line arguments and configuration in `pyproject.toml`. The configuration block uses the `[tool.deptry]` section. The README points to separate Usage and Configuration documentation, but it does not list the individual keys or command line options. No option names should therefore be inferred beyond those visible in the repository text.

Configuration becomes important when imports do not directly correspond to package names. Some libraries expose a package through a different import name, and projects may depend on packages through plugins, optional features, generated code, or runtime-loaded integrations. A static dependency checker needs an explicit project rule for such cases if its default interpretation does not match the codebase.

The README does not document handling for imports constructed dynamically with `importlib`, dependencies named only in configuration, code generated after analysis, namespace package behavior, or per-file exceptions. Those are boundaries for adopters. The full configuration documentation and project source patterns should determine whether these cases need exclusions or companion checks.

A first review should compare every `DEP001`, `DEP002`, and `DEP004` finding against the deployment model. A missing runtime dependency usually requires manifest correction. An apparently unused declaration may still serve a build or plugin requirement that is not visible as an import. The README supports the diagnostic result, but it does not establish automatic remediation.

Why deptry differs from a manual dependency audit

A manual audit is the clearest alternative. A developer can list project dependencies, search all Python sources for imports, and review the two sets by hand. This method can account for generated modules, plugin manifests, deployment scripts, and conventions specific to the repository. Its weakness is repeatability: the reviewer must remember the correct search scope, compare dependency groups, and repeat the same checks after changes.

deptry applies the comparison automatically across a directory tree and returns categorized findings with file locations and issue codes. That makes it better suited to routine developer commands and CI jobs where the same policy should run each time. It reduces reliance on a maintainer remembering every manual comparison step.

The trade-off is interpretive scope. A manual review can recognize project-specific relationships that an import scan cannot establish. deptry's documented mechanism centers on imported modules and declared requirements. It can identify inconsistencies in that model, while leaving the reviewer responsible for dependencies whose use exists outside ordinary imports.

Another alternative is treating packaging tools as the only authority. Poetry, PDM, uv, and pip manage dependencies, but the README does not claim that they perform deptry's unused and missing dependency comparison. deptry adds a separate source-oriented check rather than replacing package resolution or lockfile management.

Adding a deptry check to a Python quality workflow

The repository's `justfile` includes a `check` recipe that first runs `pre-commit` and then runs deptry against the `python` directory:

pre-commit run -a
uv run deptry python

This is a project-specific example from deptry's own repository, not a universal command template. The README's main example scans from the project root:

deptry .

The difference is the target path. A monorepo or repository with a dedicated package directory may need to scan that directory while still running from the correct working environment. The path should follow where the relevant Python files and dependency metadata reside.

The README does not state deptry's precise exit-code contract, and the repository files do not include a ready-to-copy CI configuration. A CI author should verify the current usage documentation before deciding how the command's exit status maps to job failure.

The first CI adoption can be report-only if existing dependency drift is substantial. The maintainer can classify each finding, correct manifest mistakes, and document intentional cases before making the check blocking. That sequence limits false conclusions around imports that are conditional, generated, or outside the scanner's default interpretation.

deptry maintenance, releases, and license status

The repository is not archived, and its last push was on 2026-10-16. That is the available maintenance signal; it does not by itself document the project's long-term compatibility policy. Recent release records include `0.25.1` and `0.25.0` on 2026-03-18, followed by `0.24.0` on 2025-11-09. Review the changelog when upgrading because dependency classification, parser behavior, and configuration can change between releases.

The root `pyproject.toml` requires Python `>=3.10` and lists classifiers for Python 3.10 through 3.14, along with PyPy and Rust environment markers. It also declares platform-specific dependencies such as `colorama` on Windows and `tomli` where `python_version < '3.15'`. These entries affect compatibility and environment resolution, although the README does not publish a separate support matrix.

The repository metadata declares the project under the MIT license and identifies `LICENSE` as the license file. Teams should review that file directly for the applicable permissions and conditions. This article identifies the stated license only and does not interpret legal obligations.

The repository has both `python/` and `src/` directories, a Rust manifest, test configuration, and documentation tooling. That mixed layout reflects more than a single Python script. Upgrades can therefore involve Python package dependencies, Rust crates, parser behavior, or native extension packaging. The exact release procedure is not described in the README.

Editorial conclusion

deptry is suitable for Python projects that use supported dependency metadata and want a repeatable import-to-declaration check. It is less suitable as the sole dependency authority for projects built around dynamic imports, plugins, or dependencies referenced outside ordinary Python imports. Before making it a blocking CI check, review its findings for those patterns, confirm that the project runs in its intended virtual environment, and inspect the supported configuration for dependency groups and exceptions.

Frequently asked questions

Official sources

1. License: MIT
2. osprey-oss/deptry on GitHub
3. Project website
4. README
5. Releases