Python Pentest Tool Installs Under PEP 668 (Kali/Debian)
Avoid "externally-managed-environment" with pipx and venv
Modern Kali and Debian mark system Python as externally managed (PEP 668), breaking bare `pip install` workflows. This recipe standardizes pipx for CLI tools and venv for libraries so tool installs stay isolated and the distro stays intact.
INGREDIENTS
PROMPT
Create a skill called "PEP 668 Python Tool Installer". Inputs I will provide: - OS/distro (Kali/Debian/Ubuntu) - The tool name and whether it is a CLI application or a Python library - The exact pip error output (if any) Task: 1) Choose the correct install method: apt package, pipx, or venv. 2) Output the exact commands to install, verify, and record the installed version. 3) Provide a troubleshooting checklist for PATH issues and venv activation mistakes.
What this fixes
Common symptom:
- `error: externally-managed-environment`
- Tool install notes say `pip install ...` but the distro blocks it
Prerequisites
- Python 3 installed
- `pipx` installed OR permission to install it via apt
- A writable HOME directory (for venvs/pipx)
Steps and commands
- Install pipx (recommended on Kali):
`sudo apt update && sudo apt install -y pipx`
`pipx ensurepath`
- Install a Python CLI tool cleanly:
`pipx install
Example:
`pipx install semgrep`
- If you need a library (not a CLI application), use a venv:
`python3 -m venv .venv`
`source .venv/bin/activate`
`python3 -m pip install -U pip`
`python3 -m pip install
- If you must run a repo-based tool:
`git clone
`cd
`python3 -m venv .venv && source .venv/bin/activate`
`python3 -m pip install -r requirements.txt`
- Record the installation method:
- pipx package + version
- venv requirements.txt hash/lock if applicable
Expected outputs
- The tool runs from your PATH (pipx) without breaking system packages
- `pip install` works inside the venv without triggering PEP 668 errors
Common errors and troubleshooting
- pipx installed but command not found
- Run `pipx ensurepath` and start a new shell.
- Confirm `~/.local/bin` is in PATH.
- Still seeing externally-managed-environment inside a venv
- You are not using the venv's python/pip. Run `which python3` and `which pip` to verify.
- Temptation to use `--break-system-packages`
- This can break distro-managed tooling. Prefer pipx/venv.
- pipx inject for plugins/extras
- If a pipx-installed tool needs an optional dependency: `pipx inject
`.
References
- https://www.kali.org/blog/python-externally-managed/
- https://www.kali.org/docs/general-use/python3-external-packages/
- https://peps.python.org/pep-0668/
- https://github.com/RedSiege/EyeWitness/issues/636
Example inputs
- Tool: eyewitness / semgrep / custom python CLI
- Install style: pipx (CLI) vs venv (library)