# osprey-oss/deptry architecture

> Architecture diagram of the GitHub repository osprey-oss/deptry, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/osprey-oss/deptry
- Repository: https://github.com/osprey-oss/deptry

## Overview

deptry is a Python dependency-auditing CLI. A developer selects a project; deptry reads its dependency declarations, scans Python and notebook imports, compares the two to identify dependency issues, and reports findings. The graph includes the Rust-backed import scanning layer and the documented Poetry, PDM, uv, PEP 621, and requirements-file inputs. Some orchestration details are inferred from module boundaries because the complete Core implementation and several subsystem sources were not sampled.

Main entry points: [`python/deptry/core.py`](https://github.com/osprey-oss/deptry/blob/main/python/deptry/core.py) (Core workflow), [`python/deptry/dependency_getter/builder.py`](https://github.com/osprey-oss/deptry/blob/main/python/deptry/dependency_getter/builder.py) (Getter builder), [`python/deptry/cli.py`](https://github.com/osprey-oss/deptry/blob/main/python/deptry/cli.py) (CLI), [`src/lib.rs`](https://github.com/osprey-oss/deptry/blob/main/src/lib.rs) (Rust scanner API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Command entry"]
  node_cli["CLI<br/>[cli.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_core["Core workflow<br/>[core.py]"]
end

subgraph group_scan["Project scanning"]
  node_filefinder["Python file finder"]
  node_extract["Import extraction<br/>[extract.py]"]
  node_rust["Rust scanner API<br/>[lib.rs]"]
  node_pyparse["Python parser<br/>[py.rs]"]
  node_notebookparse["Notebook parser<br/>[ipynb.rs]"]
end

subgraph group_deps["Dependency inputs"]
  node_depbuilder["Getter builder<br/>[builder.py]"]
  node_pep621["PEP 621 getter<br/>[base.py]"]
  node_poetry["Poetry getter<br/>[poetry.py]"]
  node_pdm["PDM getter<br/>[pdm.py]"]
  node_uv["uv getter<br/>[uv.py]"]
  node_requirements["Requirements getter"]
end

subgraph group_analysis["Issue analysis"]
  node_module["Module mapping<br/>[module.py]"]
  node_dispatcher["Violation dispatcher<br/>[finder.py]"]
  node_rules["Dependency rules"]
end

subgraph group_report["Reporting"]
  node_reporters["Reporters"]
end

node_developer(("Developer"))
node_project["Project files"]
node_result["Findings"]

node_developer -->|"runs"| node_cli
node_cli -->|"loads settings"| node_config
node_cli -->|"starts scan"| node_core
node_project -->|"provides files"| node_filefinder
node_core -->|"finds source files"| node_filefinder
node_core -->|"requests imports"| node_extract
node_filefinder -->|"provides paths"| node_extract
node_extract -->|"calls scanner"| node_rust
node_rust -->|"dispatches Python"| node_pyparse
node_rust -->|"dispatches notebooks"| node_notebookparse
node_project -->|"provides declarations"| node_depbuilder
node_core -->|"builds getter"| node_depbuilder
node_depbuilder -->|"selects getter"| node_pep621
node_depbuilder -->|"selects getter"| node_poetry
node_depbuilder -->|"selects getter"| node_pdm
node_depbuilder -->|"selects getter"| node_uv
node_depbuilder -->|"selects getter"| node_requirements
node_core -->|"maps imports"| node_module
node_core -->|"checks dependencies"| node_dispatcher
node_dispatcher -->|"runs rules"| node_rules
node_core -->|"reports findings"| node_reporters
node_reporters -->|"formats output"| node_result

click node_cli "https://github.com/osprey-oss/deptry/blob/main/python/deptry/cli.py"
click node_config "https://github.com/osprey-oss/deptry/blob/main/python/deptry/config.py"
click node_core "https://github.com/osprey-oss/deptry/blob/main/python/deptry/core.py"
click node_filefinder "https://github.com/osprey-oss/deptry/blob/main/python/deptry/python_file_finder.py"
click node_extract "https://github.com/osprey-oss/deptry/blob/main/python/deptry/imports/extract.py"
click node_rust "https://github.com/osprey-oss/deptry/blob/main/src/lib.rs"
click node_pyparse "https://github.com/osprey-oss/deptry/blob/main/src/imports/py.rs"
click node_notebookparse "https://github.com/osprey-oss/deptry/blob/main/src/imports/ipynb.rs"
click node_depbuilder "https://github.com/osprey-oss/deptry/blob/main/python/deptry/dependency_getter/builder.py"
click node_pep621 "https://github.com/osprey-oss/deptry/blob/main/python/deptry/dependency_getter/pep621/base.py"
click node_poetry "https://github.com/osprey-oss/deptry/blob/main/python/deptry/dependency_getter/pep621/poetry.py"
click node_pdm "https://github.com/osprey-oss/deptry/blob/main/python/deptry/dependency_getter/pep621/pdm.py"
click node_uv "https://github.com/osprey-oss/deptry/blob/main/python/deptry/dependency_getter/pep621/uv.py"
click node_requirements "https://github.com/osprey-oss/deptry/blob/main/python/deptry/dependency_getter/requirements_files.py"
click node_module "https://github.com/osprey-oss/deptry/blob/main/python/deptry/module.py"
click node_dispatcher "https://github.com/osprey-oss/deptry/blob/main/python/deptry/violations/finder.py"
click node_rules "https://github.com/osprey-oss/deptry/tree/main/python/deptry/violations"
click node_reporters "https://github.com/osprey-oss/deptry/tree/main/python/deptry/reporters"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_config,node_core toneBlue
class node_filefinder,node_extract,node_rust,node_pyparse,node_notebookparse toneAmber
class node_depbuilder,node_pep621,node_poetry,node_pdm,node_uv,node_requirements toneMint
class node_module,node_dispatcher,node_rules toneRose
class node_reporters,node_developer,node_project,node_result toneIndigo
```

## Components

### Command entry

- [CLI](https://github.com/osprey-oss/deptry/blob/main/python/deptry/cli.py): `python/deptry/cli.py`
- [Configuration](https://github.com/osprey-oss/deptry/blob/main/python/deptry/config.py): `python/deptry/config.py`
- [Core workflow](https://github.com/osprey-oss/deptry/blob/main/python/deptry/core.py): `python/deptry/core.py`

### Project scanning

- [Python file finder](https://github.com/osprey-oss/deptry/blob/main/python/deptry/python_file_finder.py): `python/deptry/python_file_finder.py`
- [Import extraction](https://github.com/osprey-oss/deptry/blob/main/python/deptry/imports/extract.py): `python/deptry/imports/extract.py`
- [Rust scanner API](https://github.com/osprey-oss/deptry/blob/main/src/lib.rs): `src/lib.rs`
- [Python parser](https://github.com/osprey-oss/deptry/blob/main/src/imports/py.rs): `src/imports/py.rs`
- [Notebook parser](https://github.com/osprey-oss/deptry/blob/main/src/imports/ipynb.rs): `src/imports/ipynb.rs`

### Dependency inputs

- [Getter builder](https://github.com/osprey-oss/deptry/blob/main/python/deptry/dependency_getter/builder.py): `python/deptry/dependency_getter/builder.py`
- [PEP 621 getter](https://github.com/osprey-oss/deptry/blob/main/python/deptry/dependency_getter/pep621/base.py): `python/deptry/dependency_getter/pep621/base.py`
- [Poetry getter](https://github.com/osprey-oss/deptry/blob/main/python/deptry/dependency_getter/pep621/poetry.py): `python/deptry/dependency_getter/pep621/poetry.py`
- [PDM getter](https://github.com/osprey-oss/deptry/blob/main/python/deptry/dependency_getter/pep621/pdm.py): `python/deptry/dependency_getter/pep621/pdm.py`
- [uv getter](https://github.com/osprey-oss/deptry/blob/main/python/deptry/dependency_getter/pep621/uv.py): `python/deptry/dependency_getter/pep621/uv.py`
- [Requirements getter](https://github.com/osprey-oss/deptry/blob/main/python/deptry/dependency_getter/requirements_files.py): `python/deptry/dependency_getter/requirements_files.py`

### Issue analysis

- [Module mapping](https://github.com/osprey-oss/deptry/blob/main/python/deptry/module.py): `python/deptry/module.py`
- [Violation dispatcher](https://github.com/osprey-oss/deptry/blob/main/python/deptry/violations/finder.py): `python/deptry/violations/finder.py`
- [Dependency rules](https://github.com/osprey-oss/deptry/tree/main/python/deptry/violations): `python/deptry/violations`

### Reporting

- [Reporters](https://github.com/osprey-oss/deptry/tree/main/python/deptry/reporters): `python/deptry/reporters`

### Other components

- **Developer**
- **Project files**
- **Findings**

## Connections

- Developer → CLI: runs
- CLI → Configuration: loads settings
- CLI → Core workflow: starts scan
- Project files → Python file finder: provides files
- Core workflow → Python file finder: finds source files
- Core workflow → Import extraction: requests imports
- Python file finder → Import extraction: provides paths
- Import extraction → Rust scanner API: calls scanner
- Rust scanner API → Python parser: dispatches Python
- Rust scanner API → Notebook parser: dispatches notebooks
- Project files → Getter builder: provides declarations
- Core workflow → Getter builder: builds getter
- Getter builder → PEP 621 getter: selects getter
- Getter builder → Poetry getter: selects getter
- Getter builder → PDM getter: selects getter
- Getter builder → uv getter: selects getter
- Getter builder → Requirements getter: selects getter
- Core workflow → Module mapping: maps imports
- Core workflow → Violation dispatcher: checks dependencies
- Violation dispatcher → Dependency rules: runs rules
- Core workflow → Reporters: reports findings
- Reporters → Findings: formats output