# Diagnose Shebang Venv Mismatch

> Identify and fix shebang mismatches when CLI tools resolve to system Python instead of their virtual environment

- Skill: `vamseeachanta/diagnose-shebang-venv-mismatch` (Agent Skill)
- Install (CLI): `npx skillmds@latest add vamseeachanta/diagnose-shebang-venv-mismatch`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vamseeachanta/diagnose-shebang-venv-mismatch/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: vamseeachanta (https://skillmd.com/u/vamseeachanta)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vamseeachanta/diagnose-shebang-venv-mismatch

---


# 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.