dead

2.1.0 verified Fri May 01 auth: no python

Dead simple Python dead code detection. Current version 2.1.0 (released 2024-12-08). Checks for unused functions, classes, variables, and imports. Release cadence is irregular, typically a few times a year. Compatible with Python >=3.9.

pip install dead

Common errors

error ModuleNotFoundError: No module named 'dead.dead' ↓

cause Breaking change in 2.0: the internal module was reorganized. 'dead.dead' no longer exists.

fix

Remove any direct imports of dead internals. Run dead only via CLI: python -m dead .

error usage: dead [-h] [--ignore pattern] [paths ...] dead: error: unrecognized arguments: --exclude ↓

cause The '--exclude' flag was renamed to '--ignore' in version 2.0.

fix

Use '--ignore' instead of '--exclude' when specifying patterns to skip.

error SyntaxError: invalid syntax ↓

cause dead requires Python >=3.9 and may parse files with syntax errors (unrelated to Python version). It will report syntax errors for files it cannot parse.

fix

Check the reported file for syntax errors. If using f-strings or other features unsupported by older Python versions, ensure your code is valid Python 3.9+.

Warnings

breaking Version 2.x is a complete rewrite. CLI arguments changed: no more -v/--verbose, --exclude replaced by --ignore. Module structure changed: 'from dead.dead import DeadCodeChecker' no longer works. Direct import of dead from Python is not supported as a library; use subprocess. ↓

fix Update CLI calls: replace '--exclude' with '--ignore'. Remove any direct Python imports of dead internals.

gotcha dead only detects *truly unused* symbols in the current project scope. It does not detect unused *exports* intended for external consumers (library code). It may also miss unused symbols behind conditional imports or dynamic access. ↓

fix Use dead as a quick check but complement with mypy's --unused-ignore or pyright's unused expression checks for deeper analysis.

deprecated The '--min-version' flag is deprecated in 2.x and will be removed in a future release. Use '--target-version' instead. ↓

fix Replace '--min-version' with '--target-version'.

Imports

DeadCodeChecker

wrong

from dead.dead import DeadCodeChecker

correct

from dead import DeadCodeChecker

Old internal path; breaks in 2.x

Quickstart

Run dead via command line. There is no stable Python API; use subprocess.

# Install: pip install dead
# Basic usage: dead .
# Always check file list first:
import subprocess
import sys

# Run from command line, not import
cmd = [sys.executable, '-m', 'dead', '--', '.']
subprocess.run(cmd, check=True)