Kali Linux "error: externally-managed-environment": Fix pip Install the Right Way

"error: externally-managed-environment" appears on Kali Linux when you run pip install outside a virtual environment. Since Python 3.12, Kali (like Debian and Ubuntu) stops pip from installing packages into the system's own Python, because those packages are managed by apt and a clash can break Kali's tools. Nothing is broken; you just need the right home for the package. For a library Kali already packages, use sudo apt install python3-name. For a command-line tool, use pipx install name. For a script or a tool cloned from GitHub, create a virtual environment with python3 -m venv venv, activate it with source venv/bin/activate, then pip install works normally. The override, --break-system-packages, works too, but it is the one option that can actually damage Kali. Below, we start from the basics, what pip and Python packages are, and then walk through every fix.

Ethan's niece Priya is studying cybersecurity, and her first week with Kali went well until a course video from 2021 told her to type sudo pip install for a tool the class was using. Kali answered with a block of red text: "error: externally-managed-environment". She tried pip install --user, which another video suggested, and got the same error. A forum post told her to add --break-system-packages, and it worked, until a week later, when two of Kali's own tools stopped starting after an update. Ethan sat with her for half an hour. He explained what the error was protecting, reinstalled the two broken packages with apt, set up pipx for her course tools and a virtual environment for her scripts, and she has not seen the error since. Every tutorial written before 2024 that says sudo pip install leads people to the same place. This guide explains why, from the ground up, and shows the modern way to do each of those old commands.

The basics: what Python, pip and packages are

Before the fix makes sense, it helps to know three words.

• Python is a programming language. Many of Kali's tools are written in it, and so are countless scripts and tools you will find on GitHub and in courses. On Kali, the command is python3.
• A package (also called a library or module) is a ready-made piece of Python code that other programs use. The requests package, for example, lets a script download web pages; scapy lets it build network packets. A tool usually needs several packages to run.
• pip is Python's own installer. It downloads packages from the Python Package Index (PyPI), a huge public library of Python packages, and installs them. The command is pip or pip3.

When a program says ModuleNotFoundError: No module named 'requests', it means a package it needs is not installed where it is looking. The traditional answer was "run pip install requests". On Kali today, that is exactly the command that triggers the externally-managed error, and the reason is the next piece of the puzzle.

The basics: two installers, one Python

Kali has two ways to install Python packages, and that is the whole story behind this error.

• apt is Kali's own package manager, the one you use for everything from Firefox to Nmap (our guide to what apt is and how it works covers the basics). Kali's team packages hundreds of Python libraries for apt, with names that start with python3-, such as python3-requests. They are tested together, so every Kali tool that needs them works.
• pip installs from PyPI, outside apt's knowledge. It is the newest version of everything, not tested against Kali's tools.

Both used to install into the same place: the system's Python, the one Kali's own tools run on. When pip upgraded a library that a Kali tool needed at a specific version, that tool could break, and apt had no idea pip had changed anything. The next apt upgrade could then overwrite pip's version, or refuse to, and things broke again. Over the years this caused a steady stream of mysteriously broken systems.

The modern rule is simple: the system Python belongs to apt. pip is still fully available, just in its own separate spaces, called virtual environments, where it cannot touch Kali's tools.

The basics: how to install pip3 in Kali Linux

Many people meet this error right after installing pip, so it is worth getting pip itself right first. Jake asked Ethan the obvious question the first time he opened Kali: "Is it pip or pip3?" On Kali today they are the same thing. Kali only has Python 3, and the pip and pip3 commands both run Python 3's pip. Tutorials say pip3 from the years when Python 2 was still around.

To install or check pip on Kali:

1. Update the package list: sudo apt update
2. Install pip with apt: sudo apt install python3-pip
3. Check it: pip3 --version. The output names the pip version and the Python version it belongs to.

That is the only correct way to install pip for Kali's system Python: through apt. Do not use get-pip.py scripts or sudo pip install --upgrade pip, which replace apt's pip with one apt does not know about. If you want the newest pip, create a virtual environment; each one has its own pip, which you can upgrade freely.

Once pip is installed, you will still see the externally-managed error if you use it outside a virtual environment. That is expected: installing pip gives you the tool, and the rest of this guide shows where to point it.

What "externally managed" means, and when it started

Python added a standard way for an operating system to say "this Python is managed by my package manager, not by pip". It is called PEP 668. The operating system places a small marker file named EXTERNALLY-MANAGED inside the Python installation (on Kali, in /usr/lib/python3.X/). When pip sees that file, it refuses to install into that Python and prints the error instead.

Debian and Ubuntu adopted it first. Kali tried it in early 2023, held it back, and made it permanent with the move to Python 3.12 around the start of 2024. Every Kali release since then behaves this way, and so do current Debian, Ubuntu and Raspberry Pi OS. To see which Python your Kali has, run:

python3 --version

If it says 3.12 or higher, this guide applies to you. Our guide to checking your Kali version shows how to see which Kali release you are running too.

Note what pip refuses: both sudo pip install (system-wide) and pip install --user (into your home folder). The second surprises people, because it never needed root, but packages in your home folder are still seen by the system Python, so they are blocked too.

The error message, line by line

The full message is long, but it actually contains the answer. The key parts look like this:

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.
    …
    create a virtual environment using python3 -m venv path/to/venv
    …
    it may be easiest to use pipx install xyz …

note: … You can override this, at the risk of breaking your Python
installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

• "try apt install python3-xyz" is route one: the apt package.
• "create a virtual environment" is route two: venv, for scripts and projects.
• "pipx install xyz" is route three: pipx, for command-line tools.
• "at the risk of breaking your Python installation or OS" is an honest description of the override. It is there for experts and throwaway machines.

Which fix should you use?

What you are installing	Best route	Example
A common library a script needs	apt, if Kali packages it	sudo apt install python3-requests
A tool you run as a command	pipx	pipx install toolname
A tool cloned from GitHub with requirements.txt	venv inside the tool's folder	python3 -m venv venv
Your own scripts and course work	One venv per project	python3 -m venv ~/venvs/course
Jupyter notebooks	venv plus ipykernel, or apt	pip install jupyter (inside venv)
A tool Kali already ships	apt, always	sudo apt install toolname

A useful habit: before installing any Python tool, check whether Kali already packages it. Many popular security tools are a single apt install away, already set up and tested.

Route 1: install the Kali package with apt

If the package you need is a common library, Kali probably has it as python3-name.

1. Update the package list: sudo apt update
2. Search for it: apt search python3-requests (replace requests with what you need). To narrow a long list, use apt list 'python3-*' | grep -i requests.
3. Install it: sudo apt install python3-requests
4. Test it: python3 -c "import requests; print(requests.__version__)"

Package names on PyPI and in apt usually match after the python3- prefix, but not always: the PyPI package beautifulsoup4 is python3-bs4 in apt, and PyYAML is python3-yaml. If the search finds nothing, our guide to "Unable to locate package" checks whether your package sources are set up correctly.

Pros: tested with Kali, updated with the rest of the system, available to every script. Cons: the version may be older than the newest on PyPI, and not everything is packaged. When you need a newer version or an unpackaged library, use a virtual environment instead.

Route 2: pipx for command-line tools

pipx is the right tool for installing a Python program you run as a command. It creates a private virtual environment for each tool automatically and puts the command on your PATH, so you get the convenience of the old sudo pip install with none of the risk.

1. Install pipx with apt: sudo apt install pipx
2. Add its command folder to your PATH: pipx ensurepath
3. Close the terminal and open a new one, so the PATH change takes effect.
4. Install a tool: pipx install toolname
5. Run it by name, like any other command.

Everyday pipx commands:

pipx list                         # see installed tools
pipx upgrade toolname             # update one tool
pipx upgrade-all                  # update everything
pipx inject toolname extra-pkg    # add a missing library to a tool's environment
pipx uninstall toolname           # remove a tool cleanly

pipx inject is the answer when a tool installed fine but complains about a missing optional module: it adds the module to that tool's own environment, not the system.

pipx installs tools from PyPI. For a tool on GitHub, pipx can install straight from the repository address too (pipx install git+https://github.com/owner/repo), as long as the project is set up as an installable package; if it only has a requirements.txt and a script, use a virtual environment instead.

Route 3: a virtual environment for scripts and GitHub tools

A virtual environment (venv) is a private folder with its own copy of Python's package space. Inside it, pip works exactly as the old tutorials expect, because it can only install into that folder. Delete the folder, and everything it installed is gone, with Kali untouched.

For a tool cloned from GitHub

git clone https://github.com/owner/tool.git
cd tool
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python3 tool.py --help
deactivate

Why does the command say "venv" twice? In python3 -m venv venv, the first venv is the name of Python's built-in tool (it has shipped with Python since version 3.3), and the second is simply the name of the folder it creates. Calling the folder venv is a common convention, not a rule: python3 -m venv myenv works the same, and you would then activate it with source myenv/bin/activate.

Line by line: download the tool, enter its folder, create a venv named venv inside it, activate it (your prompt now starts with (venv)), install everything the tool lists in requirements.txt, run the tool, and deactivate when finished. Next time, just cd into the folder and run source venv/bin/activate again before using the tool.

For your own scripts and course work

Keep one environment per course or project in a tidy place:

mkdir -p ~/venvs
python3 -m venv ~/venvs/course
source ~/venvs/course/bin/activate
pip install requests scapy

Run a venv tool without activating it

You do not have to activate a venv to use it. Running the venv's own Python directly uses its packages:

~/tools/tool/venv/bin/python ~/tools/tool/tool.py

That is also the clean way to make a shortcut: add a line to ~/.zshrc (Kali's default shell is Zsh) such as alias mytool='~/tools/tool/venv/bin/python ~/tools/tool/tool.py', then open a new terminal and type mytool.

If "python3 -m venv" fails

If creating a venv fails with a message about ensurepip not being available, the venv module is not installed. Install it with sudo apt install python3-venv and try again.

Tools that need root inside a virtual environment

Many security tools need root to capture packets or open raw sockets, and this is where Kali users get stuck. Running sudo python3 tool.py after activating a venv often fails with ModuleNotFoundError, because sudo starts a fresh environment and uses the system python3, not the venv's.

The fix is to call the venv's Python by its full path:

sudo ./venv/bin/python tool.py

Run that from the tool's folder. The tool now runs as root, with the venv's packages. If you are still getting comfortable with root, su and sudo on Kali, our guide to root and sudo on Kali explains the difference.

Do not create the venv itself with sudo. A venv owned by root cannot be updated by your normal user, which leads to "Permission denied" errors later. Create it as yourself, and use sudo only to run.

Translate old tutorials into the modern commands

The old tutorial says	Do this instead
sudo pip install requests	sudo apt install python3-requests
pip install --user sometool	pipx install sometool
pip install -r requirements.txt	python3 -m venv venv, source venv/bin/activate, then the same pip command
sudo python3 setup.py install	pipx install . (from the folder), or install into a venv
sudo pip3 install --upgrade pip	Do not upgrade the system pip; inside a venv, pip install --upgrade pip is fine
sudo python3 tool.py (after pip installs)	sudo ./venv/bin/python tool.py
pip install jupyter	Inside a venv, or sudo apt install jupyter-notebook

Keep this table handy: almost every Kali tutorial from before 2024 uses one of the commands on the left, and the right-hand column is the drop-in replacement.

The override: --break-system-packages, and when it is acceptable

pip lets you bypass the protection. You can add --break-system-packages to a single command, set the environment variable PIP_BREAK_SYSTEM_PACKAGES=1, or turn it on permanently in pip's configuration file. All three do the same thing: let pip write into the system Python again, exactly as it did before 2024.

It is called "break system packages" for a reason. The risks are concrete:

• A pip upgrade can replace a library a Kali tool depends on with a version that tool does not support, and the tool fails to start.
• The next apt upgrade can fail or quietly overwrite pip's files, breaking whatever you installed.
• The breakage is hard to trace, because nothing records which files pip changed underneath apt.

When is it acceptable? On a throwaway virtual machine or container you will delete after a lab, where speed matters more than stability. Never on your main Kali install, and never as a permanent setting. And do not delete the EXTERNALLY-MANAGED marker file to make the error go away; that removes the protection for every future command, and Kali puts the file back on Python updates anyway.

Already used --break-system-packages? How to repair Kali

If a tool broke after installing something with the override, Priya's situation, this sequence usually repairs it.

1. See what pip installed into the system. Packages installed by pip as root go into /usr/local/lib/python3.X/dist-packages; list them with ls /usr/local/lib/python3.*/dist-packages.
2. Remove the ones you added with pip, using the override one last time: sudo pip uninstall --break-system-packages package. Packages installed with --user live in ~/.local/lib/python3.X/site-packages; remove those with pip uninstall --break-system-packages package as your normal user.
3. Reinstall the Kali versions of anything that broke: sudo apt install --reinstall python3-package, plus the tool itself if needed.
4. Update fully: sudo apt update && sudo apt full-upgrade.
5. Reinstall what you needed the right way: pipx for tools, a venv for scripts.

If you set the override permanently, remove the break-system-packages line from ~/.config/pip/pip.conf (and any PIP_BREAK_SYSTEM_PACKAGES line from ~/.zshrc) so it does not happen again.

Follow-up errors people hit next

Once the externally-managed error is gone, a handful of other messages tend to appear in the first week of using pipx and virtual environments. None of them means anything is broken; each one points to a step that was skipped, usually activating the venv or refreshing the terminal. Here they are in the order people usually meet them, with the one-line fix for each.

"pip: command not found"

pip is not installed for the system Python. Install it with sudo apt install python3-pip. Inside a venv, pip is always available after activation.

"ModuleNotFoundError" right after installing

The package went into a different Python from the one running your script. Usually the venv is not activated in this terminal, or the script starts with #!/usr/bin/python3, which always uses the system Python. Activate the venv, or run the script with the venv's Python by its full path.

"command not found" after pipx install

The pipx command folder (~/.local/bin) is not on your PATH yet. Run pipx ensurepath, then open a new terminal.

"Permission denied" inside a venv

The venv was created with sudo, so it belongs to root. Delete it (sudo rm -rf venv) and create it again as your normal user.

"error: externally-managed-environment" inside a venv

The venv is not actually active, so pip is still the system one. Check with which pip: inside an active venv it points into the venv folder. Activate it again, or use ./venv/bin/pip.

Using a venv in VS Code and Jupyter

VS Code: open the project folder, press Ctrl + Shift + P, choose Python: Select Interpreter, and pick the interpreter inside your venv folder. VS Code then runs and debugs your scripts with the venv's packages.

Jupyter: inside an activated venv, run pip install jupyter ipykernel, then python -m ipykernel install --user --name course. The venv now appears as a kernel named "course" in Jupyter, so notebooks use its packages.

Other editors work the same way: PyCharm asks for a project interpreter (point it at venv/bin/python), and terminal editors simply use whatever Python is active in the terminal you start them from. The rule is always the same: the editor must run the venv's Python, or it will not see the packages you installed there.

Where each installer puts packages (and how to check)

Knowing where packages land makes most "it is installed but not found" puzzles easy to solve.

Installed by	Location	Used by
apt (python3-name)	/usr/lib/python3/dist-packages	The system Python and every Kali tool
sudo pip with the override	/usr/local/lib/python3.X/dist-packages	The system Python, ahead of apt's copies
pip --user with the override	~/.local/lib/python3.X/site-packages	The system Python, for your user
pip inside a venv	venv/lib/python3.X/site-packages	Only that venv's Python
pipx	~/.local/share/pipx/venvs/tool (command in ~/.local/bin)	Only that tool

Two commands answer "which Python, which packages" at any time. which python3 (or which pip) shows which program runs when you type the command, so you can see whether you are inside a venv. pip show package prints a package's version and its Location, telling you exactly which of the places above it lives in. The second and third rows of the table are the risky ones: anything there sits in front of apt's packages for the system Python, which is how one pip install can change the behavior of a Kali tool.

A worked example: setting up a course tool from scratch

Here is the whole process for a typical tool a course asks you to use, from a fresh Kali terminal. Replace the names with your tool's.

1. Check whether Kali already has it: apt search toolname. If it is listed, sudo apt install toolname and you are done.
2. Make a folder for tools: mkdir -p ~/tools && cd ~/tools
3. Download it: git clone https://github.com/owner/toolname.git && cd toolname
4. Read the README for anything unusual, such as system libraries it needs from apt.
5. Create and enter its environment: python3 -m venv venv && source venv/bin/activate
6. Update pip inside the venv (safe here): pip install --upgrade pip
7. Install its requirements: pip install -r requirements.txt
8. Run it: python3 toolname.py --help, or with root, sudo ./venv/bin/python toolname.py
9. Add an alias in ~/.zshrc if you will use it often, and deactivate when you finish.

If step 7 fails while building a package, the message usually names a missing system library or header (for example something ending in -dev). Install that with apt, such as sudo apt install libpcap-dev, then rerun the pip command. This is the one place where apt and pip work together: apt provides system libraries, pip provides the Python package inside the venv.

A faster modern option: uv

uv is a newer, very fast Python package and environment tool. It does the same jobs as venv, pip and pipx, often in a fraction of the time: uv venv creates an environment, uv pip install installs into it, and uv tool install installs command-line tools like pipx. You can install uv itself with pipx (pipx install uv). It respects the same externally-managed protection, so the principles in this guide are the same; uv is simply quicker once you are comfortable with the basics.

Kali on WSL (Windows Subsystem for Linux)

Many people run Kali inside Windows through WSL, and the error appears there too, because WSL's Kali is the same Kali with the same Python. Everything in this guide applies unchanged: apt, pipx and venv all work inside WSL. Two WSL-specific tips:

• Keep your projects and venvs inside the Linux file system, for example in ~/projects, not under /mnt/c/. Virtual environments on the Windows drive are much slower and can hit permission oddities.
• Windows Python is separate. If you also have Python installed on Windows, its pip is unrelated to Kali's. Inside the Kali terminal, always use the Kali commands; in VS Code, use the WSL extension so the editor uses Kali's interpreter.

Kali on a Raspberry Pi

Kali's Raspberry Pi images behave the same way: the system Python is protected, and the three routes apply. A Pi has limited RAM and slower storage, so the apt route is especially valuable there, since apt installs pre-built packages instead of compiling them. If a pip install inside a venv tries to compile a large package from source and takes a very long time or runs out of memory, look for the apt version first (apt search python3-name), or create the venv with python3 -m venv --system-site-packages venv, which lets the venv also see apt's installed packages, so you only pip-install what apt does not have.

The same error on Ubuntu, Debian and Raspberry Pi OS

Everything here applies equally to current Debian, Ubuntu (from 23.04) and Raspberry Pi OS, because they all use the same Python protection. The only differences are package names in apt (which match very closely) and, on Raspberry Pi OS, that many hardware libraries such as GPIO libraries are packaged for apt, so the apt route is especially useful there. On Windows and macOS with Python from python.org, the error does not appear, but using a virtual environment per project is still the recommended habit.

Good Python habits on Kali

1. Check apt first for any tool or library: apt search before pip install.
2. Use pipx for every Python command-line tool you install from PyPI.
3. Give every GitHub tool and every project its own venv, inside its folder.
4. Never use sudo pip, and never make the override permanent on your main install.
5. Keep Kali updated with sudo apt update && sudo apt full-upgrade, so apt's Python packages stay current.
6. When a tutorial uses old commands, translate them with the table above.

Kali "externally-managed-environment": frequently asked questions

"externally-managed-environment" is Kali protecting itself, not a fault. Once you know the system Python belongs to apt, the fix is always one of three homes for a package: apt for libraries Kali ships, pipx for tools you run as commands, and a virtual environment for everything else. Priya now starts every course tool with python3 -m venv venv without thinking about it, her Kali updates cleanly, and the old tutorials that once broke her system are now just a translation table away.

Revision note. Written October 4, 2026, as a basics-first guide to pip and the externally-managed-environment error on Kali Linux. May every package you install land in the right home. Happy breaking !