diagnose-shebang-venv-import-errors
Troubleshoot ModuleNotFoundError in CLI tools by identifying shebang-venv mismatches
Best use case
diagnose-shebang-venv-import-errors is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Troubleshoot ModuleNotFoundError in CLI tools by identifying shebang-venv mismatches
Teams using diagnose-shebang-venv-import-errors 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-import-errors/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How diagnose-shebang-venv-import-errors Compares
| Feature / Agent | diagnose-shebang-venv-import-errors | 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?
Troubleshoot ModuleNotFoundError in CLI tools by identifying shebang-venv mismatches
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 Virtual Environment Import Errors When a CLI tool fails with ModuleNotFoundError despite the package being installed, check if the shebang in `/usr/local/bin/` or `~/.local/bin/` points to system Python instead of the venv Python. Verify the actual Python interpreter being used by examining the shebang (`#!/usr/bin/env python3` vs `/path/to/venv/bin/python3`). If mismatched, update the shebang to explicitly point to the venv's Python executable. Be aware that auto-update mechanisms may revert custom shebangs—check for post-install scripts that regenerate entry points.
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
python-import-path-debugging
Diagnose ModuleNotFoundError when a package is installed but still fails to import
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-mismatch
Identify and fix shebang mismatches when CLI tools resolve to system Python instead of their virtual environment
diagnose-dirty-ntfs-mount-errors
Troubleshoot NTFS mount failures by identifying dirty volume flags and driver type