diagnose-venv-shebang-import-errors
Debugging pattern for ModuleNotFoundError when CLI entry points use wrong Python interpreter
Best use case
diagnose-venv-shebang-import-errors is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Debugging pattern for ModuleNotFoundError when CLI entry points use wrong Python interpreter
Teams using diagnose-venv-shebang-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-venv-shebang-import-errors/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How diagnose-venv-shebang-import-errors Compares
| Feature / Agent | diagnose-venv-shebang-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?
Debugging pattern for ModuleNotFoundError when CLI entry points use wrong Python interpreter
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 Virtual Environment Shebang Import Errors When a CLI tool fails with ModuleNotFoundError despite the package being installed, check if the entry point shebang (`#!/usr/bin/env python3`) resolves to the system Python instead of the venv Python. Verify by: (1) checking which python the shebang resolves to, (2) confirming the package exists in the venv but not system python, (3) updating the shebang to point directly to the venv's Python binary (e.g., `~/.venv/bin/python3`). If the shebang keeps reverting after updates, investigate post-install hooks that may regenerate entry points with generic shebangs.
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-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-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