KiKit on Linux: Fixing the externally-managed-environment Error and the Version Mismatch

ByPriya Nair

Two Problems, One Install: KiKit on Modern Linux

If you’ve hit a wall installing KiKit, you’ve probably encountered one or both of these: a version number that doesn’t match what the docs say, and pip refusing to install anything at all. Neither is a sign your system is broken.

Why the Version Numbers Don’t Match

KiKit is actually two separate things that ship under one name.

The first is a Python package — the actual engine that handles panelization, CLI commands, and PCB output generation. You install it with pip. The second is a GUI plugin that lives inside KiCad, installed through KiCad’s Plugin and Content Manager (PCM). It’s a frontend that calls into the Python backend.

These two components are versioned and released on independent schedules. The PCM repository might sit at one version while the pip package is already ahead. That’s not a documentation error — it’s just how the project ships. The Python backend tends to update more frequently.

In practice, having a newer pip version than your PCM plugin version is usually fine. The PCM side provides the GUI panel; the pip side does the actual work. If KiKit runs correctly, matching version numbers exactly isn’t a requirement.

The externally-managed-environment Error

This error is common on Ubuntu 22.04 and later, Debian 12+, Fedora 38+, and other distros that adopted PEP 668. The idea behind it is straightforward: your OS already manages some Python packages through its own package manager (apt, dnf, etc.). If pip installs something that conflicts with one of those, you could quietly break a system tool.

So newer distros block it outright. Running pip install kikit on a modern Linux system hits this wall even if your KiCad install is otherwise perfectly healthy.

Fix 1: –break-system-packages

The fastest workaround:

pip install kikit --break-system-packages

This overrides the protection for that specific pip call. On a desktop machine used for PCB design, the real-world risk is low — you’d need a conflict between KiKit’s dependencies and some other system Python tool. But it’s a blunt instrument. You’re bypassing a protection rather than working around it cleanly.

Fix 2: Install into KiCad’s Own Python

KiCad ships with its own Python interpreter, separate from the system Python. Installing KiKit into that interpreter sidesteps the whole issue because the restriction only applies to the system Python.

Open KiCad’s scripting console (Tools > Scripting Console) and find out which Python KiCad is actually using:

import sys
print(sys.executable)

Then use that interpreter to install KiKit:

/path/to/kicad-python -m pip install kikit

The exact path varies by distro and how KiCad was installed (system package manager, Flatpak, AppImage). This is the cleanest approach if you can locate the right interpreter — KiKit lands where KiCad can actually see it.

Fix 3: A Python Virtual Environment

You can also install KiKit into an isolated venv:

python3 -m venv ~/kikit-env
source ~/kikit-env/bin/activate
pip install kikit

The complication: KiCad needs to load KiKit from the right Python path. A venv isolates packages from both the system Python and KiCad’s Python, so you’ll need to either point KiCad at the venv’s interpreter or manually add the venv’s site-packages to KiCad’s Python path. It works, but it adds setup steps the other approaches don’t.

What to Avoid: Deleting EXTERNALLY-MANAGED

Some guides suggest removing the file at /usr/lib/python3.x/EXTERNALLY-MANAGED. This kills the error permanently — for every future pip call on your system. That’s a wider blast radius than most people want. The --break-system-packages flag does essentially the same thing on a per-command basis, which is meaningfully safer.

Verifying the Install

After installing, run this from your terminal:

kikit --version

Then check from inside KiCad’s scripting console:

import kikit
print(kikit.__version__)

If both return a version string, the backend is installed and visible to KiCad. The PCM plugin may show a different number — as covered above, that’s expected and not a problem as long as everything loads correctly.

Sources


Similar Posts