Skip to main content

Deadcode Logo

Find and Fix Unused Python Code

pre-commit PyPI Downloads License: AGPLv3
Buy Me a Coffee at ko-fi.com

Installation

pip install lapsed

The package is lapsed; the command it installs is deadcode.

Usage

To see unused code findings:

deadcode .

To see suggested fixes for all files:

deadcode . --fix --dry

To see suggested fixes only for foo.py file:

deadcode . --fix --dry --only foo.py

To fix:

deadcode . --fix

Tune out some of the false positives, e.g.:

deadcode . --exclude=venv,tests --ignore-names=BaseTestCase,*Mixin --ignore-names-in-files=migrations

The same options can be provided in pyproject.toml settings file:

[tool.deadcode]
exclude = ["venv", "tests"]
ignore-names = ["BaseTestCase", "*Mixin"]
ignore-names-in-files = ["migrations"]

If your project uses Tach to declare module boundaries, deadcode can read one or more tach.toml files and treat names exposed through [[interfaces]] as intentional public API (never reported as unused, the same way __all__ is treated), and skip files that belong to a module marked unchecked = true:

deadcode . --tach-config tach.toml

Pre-commit hook

Create a .pre-commit-config.yaml file in the root of your project directory, if it doesn't exist, and add the following to the file:

# See https://pre-commit.com for more information
# See https://pre-commit.com/hooks.html for more hooks
repos:
  - repo: https://github.com/ColinKennedy/deadcode
    rev: v3.2.1
    hooks:
      - id: deadcode

Command line options

Option                                    Type Meaning
--fix - Automatically remove detected unused code expressions from the code base.
--dry - Show changes which would be made in files.
--only list Filenames (or path expressions), that will be reflected in the output (and modified if needed).
--exclude list Filenames (or path expressions), which will be completely skipped without being analysed.
--ignore-names list Removes provided list of names from the output. Regexp expressions to match multiple names can also be provided, e.g. *Mixin will match all classes ending with Mixin.
--ignore-names-in-files list Ignores unused names in files, which filenames match provided path expressions.
--ignore-names-if-inherits-from list Ignores names of classes, which inherit from provided class names.
--ignore-names-if-decorated-with list Ignores names of an expression, which is decorated with one of the provided decorator names.
--ignore-bodies-of list Ignores body of an expression if its name matches any of the provided names.
--ignore-bodies-if-decorated-with list Ignores body of an expression if its decorated with one of the provided decorator names.
--ignore-bodies-if-inherits-from list Ignores body of a class if it inherits from any of the provided class names.
--ignore-definitions list Ignores definition (including name and body) if a name of an expression matches any of the provided ones.
--ignore-definitions-if-inherits-from list Ignores definition (including name and body) of a class if it inherits from any of the provided class names.
--ignore-definitions-if-decorated-with list Ignores definition (including name and body) of an expression, which is decorated with any of the provided decorator names.
--ignore-non-self-attributes - Does not report unused attributes assigned on objects other than self, e.g. foo.bar = 1. Such assignments may have side effects or be consumed by code outside of the analysed files, so they cannot safely be assumed dead.
--ignore-class-attributes - Does not report unused attributes assigned directly in a class body, e.g. THING = "blah" inside a class Foo: block. Such attributes may control behaviour of inherited/overridden methods, external frameworks, or metaclasses, so they cannot safely be assumed dead.
--tach-config list Paths to tach.toml files (see Tach). Names exposed via [[interfaces]] are treated as public API and never reported as unused; files in unchecked = true modules are skipped entirely.
--no-color - Removes colors from the output.
--count - Provides the count of the detected unused names instead of printing them all out.
--quiet - Does not output anything. Makefile still fails with exit code 1 if unused names are found.
Glossory
  • name - variable, function or class name.
  • body - code block which follows after : in function or class definition.
  • definition - whole class or function definition expression including its name and body.

Rules

Code Name Message
DC01 unused-variable Variable {name} is never used
DC02 unused-function Function {name} is never used
DC03 unused-class Class {name} is never used
DC04 unused-method Method {name} is never used
DC05 unused-attribute Attribute {name} is never used
DC06 unused-name Name {name} is never used
DC07 unused-import Import {name} is never used
DC08 unused-property Property {name} is never used
DC09 unreachable-if-block Unreachable conditional statement block
DC11 empty-file Empty Python file
DC12 commented-out-code Commented out code
DC13 unreachable-code Code after terminal statement, e.g. return, raise, continue, break
DC ignore-expression Do not show any findings for an expression, which starts on current line (this code can only be used in # noqa: DC comments)

Ignoring checks with noqa comments

Inline # noqa comments can be used to ignore deadcode checks. E.g. unused Foo class wont be detected/fixed because # noqa: DC03 comment is used:

class Foo:  # noqa: DC03
    pass

Contributing

  • make check - runs unit tests and other checks using virtual environment.

Rationale

ruff and flake8 - don't have rules for unused global code detection, only for local ones F823, F841, F842. deadcode package tries to add new DCXXX checks for detecting variables/functions/classes/files which are not used in a whole code base.

deadcode - is supposed to be used inline with other static code checkers like ruff.

There is an alternative vulture package.

Known limitations

In case there are several definitions using the same name - they all wont be reported if at least one usage of that name is being detected.

Files with syntax errors will be ignored, because deadcode uses ast to build abstract syntax tree for name usage detection.

It is assumed that deadcode will be run using the same or higher Python version as the code base is implemented in.

Feature requests

  • Replace .* with only * in regexp matching.
  • Add unused class method detection DC04 check.
  • Add --fix option to automatically remove detected dead code occourencies
  • Add a check for empty python files.
  • Split error codes into DC01, DC02, DC03 for variables, functions, class.
    • Should have different codes for ignoring name and ignoring whole definition (reserved DCxx0 - ignore name, DCxx1 - ignore definition).
    • Allow to disable each check separately using:
      • inline comment.
      • pyproject.toml file
  • Add a check for code in comments.
  • Add target python version option, if specified it will be used for code base check.
  • Add a --depth parameter to ignore nested code.. (To only check global scope use 0).
  • Add options:
    • --ignore-definitions
    • --ignore-definitions-if-inherits-from
    • --ignore-definitions-if-decorated-with
    • --ignore-names-if-inherits-from
    • --ignore-names-if-decorated-with
    • --ignore-bodies-of
    • --ignore-bodies-if-decorated-with
    • --ignore-bodies-if-inherits-from
    • --ignore-definitions
    • --ignore-definitions-if-inherits-from
    • --ignore-definitions-if-decorated-with
      • Question: would it be possible to ignore only certain types of checks for a body, e.g. only variable attributes of TypedDict and still check usage of methods and properties?
      • What expression would allow this type of precission?
  • Distinguish between definitions with same name, but different files.
  • Repeated application of deadcode till the output stops changing.
  • Unreachable code detection and fixing: this should only be scoped for if statements and only limited to primitive variables.
  • Benchmarking performance with larger projects (time, CPU and memory consumption) in order to optimize.
  • --fix could accept a list of filenames as well (only those files would be changed, but the summary could would be full). (This might be confusing, because filenames, which have to be considered are provided without any flag, --fix is expected to not accept arguments)
  • pre-commit-hook.
  • language server.
  • DC10: remove code after terminal statements like raise, return, break, continue and comes in the same scope.
  • Add ignore and per-file-ignores command line and pyproject.toml options, which allows to skip some rules.
  • Make sure that all rules are being skipped by noqa comment and all rules react to noqa: rule_id comments.
  • Include package names into code item scope (dot-separated path), e.g. "package1.package2.module.class.method.variable".
  • All options should be able to accept dot-separated path or a generic name, e.g. "marshmallow.Schema" vs "Schema", documentation should cleary demonstrate the behaviour/example that "Schema" means "*.Schema".
  • Redefinition of an existing name makes previous name unreachable, unless it is assigned somehow.
  • Check if file is still valid/parsable after automatic fixing, if not: halt the change and report error.
  • Investigate ways of extracting and backporting Python3.10+ ast implementation to lower Python versions.

Release notes

  • v2.6.0:
    • Add --ignore-class-attributes option to not report unused attributes assigned directly in a class body (e.g. THING = "blah" inside class Foo:), since such attributes may control behaviour of inherited/overridden methods, external frameworks, or metaclasses.
  • v2.5.0:
    • Add --ignore-non-self-attributes option to not report unused attributes assigned on objects other than self (e.g. foo.bar = 1), since such assignments may have side effects or be consumed by code outside of the analysed files.
  • v2.4.2:
    • Add --tach-config option to read tach.toml file(s) and treat names exposed via [[interfaces]] as public API, and skip unchecked = true modules entirely.
  • v2.4.1:
    • Add --version option to show deadcode version.
    • Use stdout for deadcode output.
  • v2.4.0:
    • Add --only option that accepts filenames only which will be reflected in the output and modified. This option can be used with --fix and --fix --dry options as well as for simple unused code detection without fixing.
  • v2.3.2:
    • Add pre-commit hook support.
    • Drop support for Python 3.8 and 3.9 versions, since their ast implementation is lacking features.
  • v2.3.1:
    • Started analysing files in bytes instead of trying to convert them into UTF-8 encoded strings.
    • Improved automatic removal of unused imports.
  • v2.3.0:
    • Add --dry option.
    • Update error codes to use DCXX format instead of DCXXX.

Metadata

Release files for lapsed 3.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for lapsed 3.4.0
File Size Uploaded Provenance Actions
lapsed-3.4.0.tar.gz 500.5 kB With provenance Details for lapsed-3.4.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for lapsed 3.4.0
File Actions
lapsed-3.4.0-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for lapsed-3.4.0-py3-none-win_amd64.whl
lapsed-3.4.0-py3-none-win32.whl Python 3 none Windows x86-32 Details for lapsed-3.4.0-py3-none-win32.whl
lapsed-3.4.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl Python 3 none Linux glibc 2.17+ x86-64 Details for lapsed-3.4.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
lapsed-3.4.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl Python 3 none Linux glibc 2.17+ ARM64 Details for lapsed-3.4.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
lapsed-3.4.0-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for lapsed-3.4.0-py3-none-macosx_11_0_arm64.whl
lapsed-3.4.0-py3-none-macosx_10_12_x86_64.whl Python 3 none macOS 10.12+ x86-64 Details for lapsed-3.4.0-py3-none-macosx_10_12_x86_64.whl

Total release size: 11.8 MB

Release files / lapsed-3.4.0.tar.gz

Download URL lapsed-3.4.0.tar.gz
Size 500.5 kB
Tags Source
SHA-256 checksum
How to use checksums
5484495a6c9e97259df630b8aed0692b33830996edd5f0cbb0170d4c3c072874
BLAKE2b-256 checksum
How to use checksums
388f916266504f85374f9f37bf61aa1eb77fa43f1bdf409c7111d5a3f4cdb097
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / lapsed-3.4.0-py3-none-win_amd64.whl

Download URL lapsed-3.4.0-py3-none-win_amd64.whl
Size 1.9 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
92ae965dd7f0c44b07a0d653576c8edcbec7461f5b72e05ade6e87d8dcc36424
BLAKE2b-256 checksum
How to use checksums
ec643e31a7e9539338cb02827576d5673432fac2170598b6ebf1815c79891f63
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / lapsed-3.4.0-py3-none-win32.whl

Download URL lapsed-3.4.0-py3-none-win32.whl
Size 1.8 MB
Tags Python 3 Windows x86-32
SHA-256 checksum
How to use checksums
b38a343e24ea97dafcd15e15e0c0a51237f600ab05e9b24d391aca1060e80d99
BLAKE2b-256 checksum
How to use checksums
830de80fc2a908c947b67608e1e8916b5578317a27e92f8598e1744661211765
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / lapsed-3.4.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL lapsed-3.4.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 1.9 MB
Tags Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum
How to use checksums
1c5e605e136bac24f6593b65822cf84db518f47955e8f182a56bd64c040bd7ff
BLAKE2b-256 checksum
How to use checksums
f709d7f9859b0d4801841e0e32b139c36af299d32c58cbf60afb34920686147e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / lapsed-3.4.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

Download URL lapsed-3.4.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Size 1.9 MB
Tags Linux glibc 2.17+ ARM64 Python 3
SHA-256 checksum
How to use checksums
8e5c9349a95244df42b29bb040fd76138b822c3ad71a4aa15d52fb23fe146f24
BLAKE2b-256 checksum
How to use checksums
a6f7a44a033e109c533bdb29f490ea009ec3ee8ee9e2c8f516c3b121cb77ab91
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / lapsed-3.4.0-py3-none-macosx_11_0_arm64.whl

Download URL lapsed-3.4.0-py3-none-macosx_11_0_arm64.whl
Size 1.8 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
4aeaff98f97bfb07f9be7e0c9a4d8e6654fb417cd7467547f7be9ff6d62d3952
BLAKE2b-256 checksum
How to use checksums
89acd7676b97b21ac4a2177ab1979f369ee131dec1f6a577adfbf25d3288bff5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / lapsed-3.4.0-py3-none-macosx_10_12_x86_64.whl

Download URL lapsed-3.4.0-py3-none-macosx_10_12_x86_64.whl
Size 1.9 MB
Tags Python 3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
4844dae0629e397150e1de4172f2dc9585febf5b51be7cb3ccfec9aac6c2a81e
BLAKE2b-256 checksum
How to use checksums
23d43274b66d3c83fbc56646741eefc1b81a0bce115b0c00bebc90e85581d325
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for lapsed 3.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 7 files in this release have been uploaded with provenance metadata.

Select from 7 files

Attestation for lapsed-3.4.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page