HOWTO · Python

ImportError: Kein Modul namens Setuptools

Dieses Tutorial behandelt den ImportError no module named setuptools-Fehler und bietet eine Lösung, um ihn in Python zu beheben.

Auf dieser Seite

Python meldet ImportError: No module named setuptools — unter Python 3 meist als ModuleNotFoundError: No module named 'setuptools' —, wenn der Interpreter, der Ihren Code ausführt, das Paket setuptools nicht finden kann. setuptools ist die seit Langem etablierte Build- und Distributionsbibliothek für Python-Pakete, und zahlreiche Tools sowie setup.py-basierte Installationen setzen sie weiterhin voraus. Die Lösung besteht fast immer darin, sie zu installieren — allerdings in dieselbe Umgebung, die Ihren Code ausführt, und genau daran scheitern die meisten Versuche. Diese Anleitung zeigt, wie Sie diese Umgebung identifizieren, setuptools über pip oder conda installieren und bestätigen, dass die Korrektur funktioniert hat.

Den Fehler verstehen und die aktive Python-Umgebung identifizieren

Zwei Situationen verursachen diesen Fehler am häufigsten:

  • setuptools wurde in der Umgebung nie installiert. Frische venv-Umgebungen, die von Python 3.12 und neuer erstellt wurden, sowie mehrere Pythons aus Linux-Distributionen liefern es nicht mehr mit.
  • setuptools ist installiert, aber für einen anderen Interpreter. Ein Rechner kann mehrere Python-Installationen beherbergen — ein System-Python, eine oder mehrere venv-Umgebungen, eine conda-Basis — und die Installation in einer davon hilft den anderen nicht.

Die erste diagnostische Frage lautet daher nicht „ist setuptools installiert?“, sondern „welcher Interpreter führt den fehlschlagenden Code aus, und kann dieser Interpreter setuptools sehen?“ Der Pfad des Interpreters ist nur einen Befehl entfernt: python -c "import sys; print(sys.executable)". sys.executable rät nie — anders als which python oder where python, die nur zeigen, was die Shell zuerst auflöst. Liegt der ausgegebene Pfad innerhalb eines venv-Verzeichnisses (zum Beispiel .venv/bin/python), läuft der Code in dieser virtuellen Umgebung.

Als Nächstes zählt die Sicht desselben Interpreters auf die installierten Pakete; prüfen Sie also, welche Pakete er tatsächlich sehen kann. Führen Sie dieses Beispiel aus:

Der Code und die angezeigten Bezeichnungen oder Ausgaben in diesem Abschnitt bleiben auf Englisch.

import importlib.util

for name in ("pip", "setuptools"):
    found = importlib.util.find_spec(name) is not None
    print(name, "->", "found" if found else "missing")
pip -> found
setuptools -> missing

find_spec meldet, ob das Importsystem ein Paket finden kann, ohne es zu importieren. Führen Sie das Skript mit demselben Interpreter aus, der den fehlschlagenden Code ausführt. Hier bedeutet pip -> found, dass dieser Interpreter über ein funktionierendes Installationsprogramm verfügt, während setuptools -> missing bestätigt, dass das Paket für ihn unsichtbar ist — genau das behebt die Installation im nächsten Abschnitt. Gibt Ihr Lauf dagegen setuptools -> found aus und das Programm schlägt dennoch fehl, startet ein anderer Interpreter das Programm — häufig der Fall, wenn eine IDE, ein Task-Runner oder ein Cron-Job getrennt von Ihrem Terminal konfiguriert ist. Der letzte Abschnitt behandelt diesen Fall.

Es lohnt sich außerdem, die Grenze der Namensauflösung direkt zu sehen. Wenn das Importsystem einen Namen nicht auflösen kann, löst der Interpreter ModuleNotFoundError aus — eine Unterklasse von ImportError — und nennt das Modul, das er nicht finden konnte. Sie können genau diese Fehlersignatur reproduzieren, ohne etwas zu deinstallieren: Das folgende Beispiel fügt einen Import-Finder ein, der setuptools verbirgt, versetzt den Interpreter damit in denselben Zustand wie bei einer fehlenden Installation und zeichnet auf, was der fehlgeschlagene Import meldet.

import importlib.abc
import sys

class HideSetuptools(importlib.abc.MetaPathFinder):
    def find_spec(self, name, path=None, target=None):
        if name == "setuptools":
            raise ModuleNotFoundError("No module named 'setuptools'")
        return None

sys.meta_path.insert(0, HideSetuptools())

try:
    import setuptools
except ModuleNotFoundError as exc:
    print(type(exc).__name__ + ":", exc)
    print("setuptools is not visible to this interpreter")
ModuleNotFoundError: No module named 'setuptools'
setuptools is not visible to this interpreter

Endet der Traceback unter Ihrem fehlschlagenden Programm mit derselben ModuleNotFoundError-Zeile, die setuptools nennt, trifft die obige Diagnose zu und die Installation im nächsten Abschnitt löst das Problem. Ein anderer Fehler im Traceback — etwa eine fehlende Abhängigkeit von setuptools selbst oder ein fehlgeschlagener setup.py-Build-Schritt — deutet auf eine andere Ursache hin; vergleichen Sie daher die letzte Ausnahmezeile, bevor Sie etwas installieren.

setuptools in der Umgebung installieren, die Ihren Code ausführt

Der zuverlässige Installationsbefehl bindet pip über das Flag -m an einen bestimmten Interpreter, sodass das Paket genau dort landet, wo dieser Interpreter sucht: python -m pip install setuptools.

Ersetzen Sie python durch den Interpreter, den der vorherige Schritt gemeldet hat: python3, py -3 über den Windows-Launcher oder einen vollständigen Pfad wie .venv/bin/python -m pip install setuptools. Innerhalb eines aktivierten venv zeigt einfaches python bereits in die Umgebung, sodass Aktivierung plus python -m pip der einfachste Weg für venv-verwaltete Projekte ist. Vermeiden Sie es, setuptools global „nur für den Fall“ zu installieren — installieren Sie es für den Interpreter, der den fehlschlagenden Code ausführt, und bevorzugen Sie für Projektarbeit virtuelle Umgebungen gegenüber dem System-Python.

Wird die Umgebung von conda verwaltet, nutzen Sie stattdessen den eigenen Installer von conda, damit er das Paket in seinen eigenen Metadaten verzeichnet: Aktivieren Sie die Zielumgebung und führen Sie conda install setuptools aus, oder wählen Sie sie direkt mit conda install -n myenv setuptools an. Der conda-Weg gilt nur für conda-verwaltete Umgebungen; für alles andere ist der obige Befehl python -m pip die allgemeine Lösung.

Im Hintergrund lädt pip das Paket aus dem Python Package Index (PyPI) herunter und installiert es im site-packages-Verzeichnis der Umgebung — genau dem Ort, den das Importsystem durchsucht. Der Rechner muss daher PyPI oder einen konfigurierten Paket-Mirror erreichen können; wenn Installationen wiederholt in Zeitüberschreitungen laufen oder pypi.org nicht auflösen können, prüfen Sie vor einem erneuten Versuch Ihr Netzwerk, Ihren Proxy oder die Index-Konfiguration von pip.

Die Installation überprüfen und hartnäckige Fehler beheben

Überprüfen Sie das Ergebnis mit derselben Interpreter-Bindung wie bei der Installation: python -m pip show setuptools. Bei Erfolg gibt er die Paketmetadaten aus — Name, Version, Summary und eine Location-Zeile. Die Location muss unter demselben Umgebungspräfix liegen, das sys.executable zuvor gemeldet hat — ist das nicht der Fall, haben Sie in eine andere Umgebung installiert als die, die den Code ausführt. Gibt pip die Meldung WARNING: Package(s) not found: setuptools aus, ist das Paket für diesen Interpreter überhaupt nicht installiert; gehen Sie zurück und installieren Sie es mit der korrekten -m pip-Bindung.

Eine letzte Prüfung ist python -c "import setuptools", ausgeführt mit demselben Interpreter; sie sollte nichts ausgeben und zur Eingabeaufforderung zurückkehren. Löst sie erneut den ImportError aus, kann der Interpreter das Paket weiterhin nicht sehen.

Wenn der Fehler weiterhin besteht, arbeiten Sie diese Ursachen der Reihe nach durch:

  • Abweichender Interpreter. Der Code wird von einem anderen Interpreter gestartet als dem, den das Terminal verwendet. Vergleichen Sie den Starter des Skripts (IDE-Interpreter-Einstellung, Shebang-Zeile, cron-Eintrag) mit der obigen sys.executable-Ausgabe und richten Sie dann entweder den Starter auf diesen Interpreter aus oder wiederholen Sie die Installation über dessen -m pip.
  • Veraltetes pip. Ein altes pip kann moderne Pakete unter Umständen gar nicht mehr abrufen oder installieren. Wenn die Installationen selbst fehlerhaft sind, aktualisieren Sie es — an denselben Interpreter gebunden — mit python -m pip install --upgrade pip und wiederholen Sie dann die setuptools-Installation. Dies ist ein bedingter Schritt für ein defektes oder veraltetes Installationsprogramm, keine allgemeine Ursache des ImportError.
  • Beschädigte Umgebung. Wenn Aktivierungsskripte oder site-packages beschädigt sind, ist ein sauberes venv schneller als eine Reparatur. Erstellen Sie eines mit python -m venv .venv, aktivieren Sie es mit source .venv/bin/activate unter macOS und Linux oder .venv\Scripts\activate unter Windows, installieren Sie dann setuptools und Ihre Projektabhängigkeiten neu und führen Sie den Code dort erneut aus.
  • Importe zur Build-Zeit. Tritt der Fehler auf, während pip etwas anderes aus dem Quellcode installiert, kann der fehlschlagende Import von einem setup.py-Build stammen, der mit --no-build-isolation läuft, oder vom direkten Aufruf von setup.py. Installieren Sie setuptools für den Interpreter, der den Build ausführt.

Sobald pip show das Paket unter dem richtigen Präfix meldet und import setuptools mit demselben Interpreter gelingt, ist der ImportError behoben. Interpreter-gebundene Installationen — python -m pip statt eines nackten pip — verhindern, dass diese Fehlerklasse zurückkehrt.