DOCSEARCHbyAlgolia
Submit Docs

deptry

repository·main·Indexed 23 days ago

https://github.com/osprey-oss/deptry

A command-line tool for detecting dependency issues in Python projects, such as unused dependencies, missing declarations, and transitive dependencies. It supports Poetry, pip, PDM, uv, and PEP 621 specifications, scanning Python files to ensure dependency lists are accurate and minimal.

Tokens
6.5K
Snippets
28
Records
35
Agent score
75%

What's inside deptry

  1. Overview of deptry rules and violations

    main

    deptry checks your Python project against five specific dependency rules to ensure your dependency list is accurate, minimal, and correctly categorized.

    Managing Violations

    • Disable a rule: Use the ignore configuration flag.
    • Ignore specific items: Use the per-rule-ignores configuration flag to ignore specific dependencies or modules for a rule.
    • Exclude specific lines: Use inline ignore comments to exclude individual import lines from being checked.
    | Code   | Description                        | More information                                    |
|--------|------------------------------------| ----------------------------------------------------|
| DEP001 | Project should not contain missing dependencies               | [link](#missing-dependencies-dep001)                |
| DEP002 | Project should not contain unused dependencies               | [link](#unused-dependencies-dep002)                 |
| DEP003 | Project should not use transitive dependencies            | [link](#transitive-dependencies-dep003)             |
| DEP004 | Project should not use development dependencies in non-development code | [link](#misplaced-development-dependencies-dep004)  |
| DEP005 | Project should not contain dependencies that are in the standard library    | [link](#standard-library-dependencies-dep005)       |

  3. Extract dependencies from Poetry

    main

    deptry supports both PEP 621 and legacy Poetry syntax.

    Regular Dependencies

    • If [project.dependencies] is empty or not set, deptry extracts regular dependencies from [tool.poetry.dependencies].
    • If [project.dependencies] contains at least one dependency, deptry will NOT extract from [tool.poetry.dependencies]. In this mode, [tool.poetry.dependencies] is treated as an enrichment (e.g., for specifying sources) rather than a source of new dependencies.

    Development Dependencies

    Deptry extracts development dependencies from:

    • [tool.poetry.group.<group>.dependencies] sections
    • [tool.poetry.dev-dependencies] (legacy section)
    # Example: Poetry enrichment mode
[project]
name = "foo"
dependencies = ["httpx"]

[tool.poetry.dependencies]
httpx = { git = "https://github.com/encode/httpx", tag = "0.28.1" }
urllib3 = "2.3.0" # This will NOT be extracted because [project.dependencies] is not empty

# Example: Development dependencies
[tool.poetry.dev-dependencies]
mypy = "1.14.1"

[tool.poetry.group.test.dependencies]
pytest = "8.3.3"

  4. Extract dependencies from uv

    main

    If a [tool.uv.dev-dependencies] section is present in pyproject.toml, deptry assumes uv is the dependency manager. It will extract PEP 621 dependencies plus additional uv development dependencies from the dev-dependencies entry under the [tool.uv] section.

    [tool.uv]
dev-dependencies = [
    "mkdocs==1.6.1",
    "pytest==8.3.3",
    "pytest-cov==5.0.0",
]

  5. Extract dependencies from requirements.txt (pip/pip-tools)

    main

    deptry supports the standard requirements.txt format used by pip and pip-tools.

    Default Behavior

    • Regular dependencies: Looked for in requirements.txt (or requirements.in if using pip-tools).
    • Development dependencies: Looked for in dev-requirements.txt and requirements-dev.txt.
    • Recursive files: If a requirements file uses -r other-requirements.txt, deptry includes those dependencies.

    Customizing File Locations

    If you use non-standard filenames, use these options:

    • --requirements-files (or requirements_files in pyproject.toml) to specify regular dependency files.
    • --requirements-files-dev (or requirements_files_dev in pyproject.toml) to specify development dependency files.
    # requirements.txt
click>=8.0.0
orjson>=3.0.0

# dev-requirements.txt
mkdocs==1.6.1
pytest==8.3.3

  6. How deptry extracts dependencies and imports

    main

    Dependency Extraction

    deptry extracts dependencies from various dependency managers and categorizes them into two groups:

    • Regular dependencies: Intended for use within the codebase.
    • Development dependencies: Intended for use outside the codebase (e.g., pytest, mypy, ruff).

    Note: deptry will not run the Unused dependencies (DEP002) check on development dependencies.

    Import Extraction

    deptry scans .py and .ipynb files for imports. It extracts imports regardless of where they appear (top-level, inside functions, etc.).

    Exceptions:

    • TYPE_CHECKING: Imports guarded by if TYPE_CHECKING: (often used with from __future__ import annotations) are ignored and not considered problematic.
    • Dynamic Imports: deptry supports imports created via importlib.import_module("string_literal"), but cannot detect imports where the argument is a variable or attribute.

  7. How PEP 621 dependency extraction works

    main

    deptry uses the presence of a [project] section in pyproject.toml to identify projects using the PEP 621 standard.

    By default, it extracts:

    • Regular dependencies: From the dependencies entry under [project] and groups under [project.optional-dependencies].
    • Development dependencies: From groups under the [dependency-groups] section.

    Note: Groups under [project.optional-dependencies] can be treated as development dependency groups using the --optional-dependencies-dev-groups CLI argument or the optional_dependencies_dev_groups configuration key in pyproject.toml.

    [project]
name = "foo"
dependencies = ["orjson>=3.0.0"]

[project.optional-dependencies]
cli = ["click>=8.0.0"]
http = [
    "httpx>=0.27.0",
    "uvicorn>=0.32.0",
]

[dependency-groups]
docs = ["mkdocs==1.6.1"]
test = [
    "pytest==8.3.3",
    "pytest-cov==5.0.0",
]

  8. Extract dependencies from Setuptools (Dynamic)

    main

    When using setuptools with dynamic metadata, deptry can extract dependencies from files referenced in pyproject.toml.

    Groups under [tool.setuptools.dynamic.optional-dependencies] can be flagged as development dependency groups using the --pep621-dev-dependency-groups CLI argument or the pep_621_dev_dependency_groups configuration key.

    [build-backend]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

[project]
name = "foo"
dynamic = ["dependencies", "optional-dependencies"]

[tool.setuptools.dynamic]
dependencies = { file = ["requirements.txt"] }

[tool.setuptools.dynamic.optional-dependencies]
cli = { file = ["cli-requirements.txt"] }

  9. Install deptry

    main

    You can add deptry to your project using your preferred package manager.

    Important: If using pip, you must install deptry within your project's virtual environment. Installing it globally will fail because deptry requires access to the metadata of the packages installed in your specific virtual environment.

    # Install with uv
uv add --dev deptry

# Install with poetry
poetry add --dev deptry

# Install with pip
pip install deptry

  10. Configure deptry via pyproject.toml

    main

    You can configure deptry by adding a [tool.deptry] section to your pyproject.toml file. This allows you to persist settings like dependency file locations, exclusion patterns, and rule ignores without passing CLI flags every time.

    [tool.deptry]
exclude = ["a_directory", "a_python_file\\.py", "a_pattern/.*"]
ignore = ["DEP003", "DEP004"]
requirements_files = ["requirements.txt"]

  11. Configure deptry via pyproject.toml or CLI

    main

    You can configure deptry using two methods:

    1. pyproject.toml: Add a [tool.deptry] section to your project's configuration file.
    2. Command Line Arguments: Pass configuration options directly when running the deptry command.

    Lookup Hierarchy

    When a configuration option is provided in multiple places, deptry resolves the value using the following priority (highest to lowest):

    1. CLI arguments (overrides everything)
    2. [tool.deptry] section in pyproject.toml (overrides defaults)
    3. Default values

  12. Run deptry for basic usage

    main

    You can run deptry by providing the path to the root directory of the project you want to scan. If your project has multiple source directories, you can provide multiple paths.

    To use a specific pyproject.toml file (for example, if it is located in a different directory than where you are running the command), use the --config argument.