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.
