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.
laurigates