diagnose-venv-shebang-conflicts
Debugging pattern for resolving ModuleNotFoundError when CLI entry points use wrong Python interpreter
Best use case
diagnose-venv-shebang-conflicts is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Debugging pattern for resolving ModuleNotFoundError when CLI entry points use wrong Python interpreter
Teams using diagnose-venv-shebang-conflicts 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-conflicts/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How diagnose-venv-shebang-conflicts Compares
| Feature / Agent | diagnose-venv-shebang-conflicts | 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 resolving 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 Conflicts When a CLI tool installed via pip fails with ModuleNotFoundError despite packages being installed, check if the entry point shebang points outside the venv. Compare the shebang in `~/.local/bin/<tool>` against the venv's actual python path (`<venv>/bin/python3`). If they differ, the generic `#!/usr/bin/env python3` may resolve to system python lacking venv packages. Update the shebang to point directly to the venv's python, or investigate if package updates are regenerating entry points with incorrect 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.
work-around-merge-conflicts-in-test-execution
Run tests when repo has unresolved merge conflicts in config files by bypassing broken configs and executing tests directly
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-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
diagnose-and-mount-dirty-ntfs-drives
Troubleshoot and mount NTFS external drives blocked by dirty filesystem flags