diagnose-shebang-venv-mismatch
Identify and fix shebang mismatches when CLI tools resolve to system Python instead of their virtual environment
Best use case
diagnose-shebang-venv-mismatch is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Identify and fix shebang mismatches when CLI tools resolve to system Python instead of their virtual environment
Teams using diagnose-shebang-venv-mismatch should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/diagnose-shebang-venv-mismatch/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How diagnose-shebang-venv-mismatch Compares
| Feature / Agent | diagnose-shebang-venv-mismatch | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Identify and fix shebang mismatches when CLI tools resolve to system Python instead of their virtual environment
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Diagnose Shebang vs Venv Mismatch When a CLI tool fails with ModuleNotFoundError for packages that are installed in its venv, the entry point shebang may be pointing to system Python instead of the venv's Python. Check the shebang in `/usr/local/bin/<tool>` or `~/.local/bin/<tool>` — it should reference the venv's Python (`/path/to/venv/bin/python3`), not `/usr/bin/env python3`. Update the shebang directly or check if the tool's update process regenerates it with a generic shebang, requiring a permanent fix strategy.
Related Skills
digitalmodel-worktree-test-execution-with-shared-venv
Run digitalmodel tests from isolated worktrees without uv editable-dependency failures by using the main repo's existing virtualenv and PYTHONPATH.
diagnose
Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is broken/throwing/failing, or describes a performance regression.
python-import-path-mismatch-debugging
Diagnose and fix ModuleNotFoundError when a package is installed but imports still fail due to environment/path mismatches
fix-symlink-shebang-persistence
Permanently fix shebang issues in symlinked CLI tools that get overwritten by git updates
diagnose-venv-shebang-mismatch
Diagnose and fix ModuleNotFoundError caused by entry point shebang pointing outside virtual environment
diagnose-venv-shebang-import-errors
Debugging pattern for ModuleNotFoundError when CLI entry points use wrong Python interpreter
diagnose-venv-shebang-conflicts
Debugging pattern for resolving ModuleNotFoundError when CLI entry points use wrong Python interpreter
diagnose-symlink-shebang-persistence
Fix persistent shebang issues in symlinked CLI entry points that revert after git operations
diagnose-shebang-virtualenv-import-errors
Debugging pattern for ModuleNotFoundError when CLI entry points use wrong Python interpreter
diagnose-shebang-venv-import-errors
Troubleshoot ModuleNotFoundError in CLI tools by identifying shebang-venv mismatches
diagnose-dirty-ntfs-mount-errors
Troubleshoot NTFS mount failures by identifying dirty volume flags and driver type
diagnose-and-mount-dirty-ntfs-drives
Troubleshoot and mount NTFS external drives blocked by dirty filesystem flags