# Diagnose Shebang Venv Import Errors

> Troubleshoot ModuleNotFoundError in CLI tools by identifying shebang-venv mismatches

- Skill: `vamseeachanta/diagnose-shebang-venv-import-errors` (Agent Skill)
- Install (CLI): `npx skillmds@latest add vamseeachanta/diagnose-shebang-venv-import-errors`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vamseeachanta/diagnose-shebang-venv-import-errors/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-import-errors

---


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