vulture-dead-code

Vulture and deadcode - Dead Code Detection

Tools for finding unused Python code including functions, classes, variables, imports, and attributes.

When to Use This Skill

Use this skill when...	Use another tool instead when...
Detecting unused functions, classes, variables	Finding unused imports only (use ruff --select F401)
Cleaning up dead code in a codebase	Checking type correctness (use basedpyright)
Enforcing code hygiene in CI	Formatting code (use ruff format)
Generating whitelists for false positives	Running general linting (use ruff check)

Overview

Vulture (mature, confidence-based) and deadcode (newer, AST-based) both detect unused code but with different approaches:

Feature	Vulture	deadcode
Approach	Static analysis + confidence scores	AST-based detection
Accuracy	Confidence scores (60-100%)	High accuracy, fewer false positives
Speed	Fast	Very fast
Configuration	Whitelist files	TOML configuration
Maturity	Mature (2012)	Newer (2023+)
Best For	Large codebases, gradual cleanup	New projects, strict enforcement

Installation

# Install vulture
uv add --dev vulture

# Install deadcode (newer alternative)
uv add --dev deadcode

# Install both for comparison
uv add --dev vulture deadcode

Vulture - Confidence-Based Detection

Basic Usage

# Check entire project
vulture .

# Check specific files/directories
vulture src/ tests/

# Minimum confidence threshold (60-100%)
vulture --min-confidence 80 .

# Exclude patterns
vulture . --exclude "**/migrations/*,**/tests/*"

# Sort by confidence
vulture --sort-by-size .

# Generate whitelist of current issues
vulture . --make-whitelist > vulture_whitelist.py

Configuration (pyproject.toml)

[tool.vulture]
min_confidence = 80
paths = ["src", "tests"]
exclude = [
    "**/migrations/*",
    "**/__pycache__/*",
    ".venv/*"
]
ignore_decorators = [
    "@app.route",
    "@pytest.fixture",
    "@property",
    "@staticmethod",
    "@classmethod"
]
ignore_names = [
    "test_*",
    "setUp*",
    "tearDown*",
]

deadcode - AST-Based Detection

Basic Usage

# Check entire project
deadcode .

# Check specific files/directories
deadcode src/

# Verbose output
deadcode --verbose .

# Dry run (show what would be removed)
deadcode --dry-run .

# Show unreachable code
deadcode --show-unreachable .

# Generate configuration
deadcode --init

Configuration (pyproject.toml)

[tool.deadcode]
paths = ["src"]
exclude = [
    "tests/*",
    "**/__pycache__/*",
    "**/migrations/*",
]
ignore_names = [
    "test_*",
    "setUp",
    "tearDown",
    "main",
]
ignore_decorators = [
    "app.route",
    "pytest.fixture",
    "property",
    "staticmethod",
    "classmethod",
    "abstractmethod"
]
show_unreachable = false

Choosing Between Tools

Choose Vulture when...	Choose deadcode when...
Large, mature codebases	New projects
Need confidence-based filtering	Want fewer false positives
Need whitelist file approach	Prefer TOML configuration
Dynamic code (getattr, exec)	Need unreachable code detection

Hybrid Approach

# Run both for comprehensive detection
vulture --min-confidence 80 .
deadcode .

Agentic Optimizations

Context	Command
Quick vulture check	vulture --min-confidence 90 .
Quick deadcode check	deadcode .
Generate whitelist	vulture . --make-whitelist > vulture_whitelist.py
CI enforcement	vulture --min-confidence 80 . vulture_whitelist.py
Unreachable code	deadcode --show-unreachable .
Combined check	vulture --min-confidence 80 . && deadcode .

Quick Reference

Vulture Flags

Flag	Description
--min-confidence N	Minimum confidence (60-100%)
--exclude PATTERN	Exclude glob patterns
--sort-by-size	Sort results by size
--make-whitelist	Generate whitelist file

deadcode Flags

Flag	Description
--verbose	Verbose output
--dry-run	Show without modifying
--show-unreachable	Detect unreachable code
--init	Generate configuration
--strict	Strict enforcement mode

For detailed examples, advanced patterns, and best practices, see REFERENCE.md.