Eine Python-Wheel-Datei (.whl) installieren

Um eine Python-Datei im Format .whl zu installieren, wählen Sie ein Wheel, das zu Ihrem Python-Interpreter und Ihrer Plattform passt. Führen Sie dann im Terminal python -m pip install "/path/to/package.whl" aus. Dadurch wird das Paket in der Umgebung installiert, zu der der mit python aufgerufene Interpreter gehört. Ein Wheel ist eine fertig installierbare Paketdistribution. Normalerweise installieren Sie es mit pip, anstatt es selbst zu entpacken.

.whl-Dateien verstehen

Ein Wheel ist ein Format für erstellte Python-Paketdistributionen. Es handelt sich um ein ZIP-basiertes Archiv mit Paketdateien und Metadaten in einer Struktur, die Installationstools verstehen. Ein Wheel kann Python-Code, kompilierte Erweiterungen oder beides enthalten. Wenn Sie ein kompatibles Wheel installieren, müssen Sie das Paket normalerweise nicht auf Ihrem Rechner aus dem Quellcode erstellen.

Der Dateiname gibt Distribution, Version und Kompatibilitätstags an; auf ihn folgt die Endung .whl. Die Tags beschreiben unter anderem die Python-Implementierung und -Version, die Application Binary Interface (ABI) sowie das Betriebssystem oder die Prozessorplattform. Ein mit py3-none-any gekennzeichnetes Wheel ist im Allgemeinen für Python 3 ohne plattformspezifische Binärkomponente vorgesehen. Andere Wheels können auf bestimmte Python-Builds oder Systeme beschränkt sein.

Ein kompatibles Wheel auswählen

Beziehen Sie die Datei vom Paketpublisher oder aus einem Paketindex, dem Sie vertrauen. Prüfen Sie vor dem Herunterladen die Installationsanweisungen des Pakets und wählen Sie ein Wheel, dessen Tags zum Python-Interpreter und Rechner passen, auf denen Sie es installieren möchten. Eine Datei, die für ein anderes Betriebssystem, eine andere Prozessorarchitektur oder eine andere Python-ABI erstellt wurde, ist möglicherweise nicht verwendbar, selbst wenn der Paketname stimmt.

Mit python --version und python -m pip --version können Sie prüfen, auf welchen Interpreter sich ein Befehl bezieht. Wenn auf Ihrem System python3 der Befehl für Python 3 ist, verwenden Sie konsequent python3. Haben Sie mehrere Python-Installationen oder eine virtuelle Umgebung, aktivieren Sie zuerst die gewünschte Umgebung oder verwenden Sie direkt den Pfad zu ihrem Interpreter. So vermeiden Sie, ein Paket in einer Umgebung zu installieren und anschließend zu versuchen, es aus einer anderen zu importieren.

Ein lokales Wheel ist nützlich, wenn der Zielrechner nur eingeschränkten oder gar keinen Internetzugang hat. Laden Sie das Wheel und alle benötigten Abhängigkeits-Wheels auf einem verbundenen Rechner herunter, übertragen Sie sie auf den Zielrechner und installieren Sie die lokalen Dateien. Mit den Optionen --no-index und --find-links können Sie pip anweisen, Abhängigkeiten in einem lokalen Verzeichnis zu suchen. Fehlende Abhängigkeiten werden dadurch jedoch nicht automatisch bereitgestellt.

Eine .whl-Datei mit pip installieren

Verwenden Sie python -m pip, damit pip mit dem durch python bezeichneten Interpreter ausgeführt wird. Ersetzen Sie den Beispielpfad durch den Speicherort und Dateinamen Ihres Wheels:

from pathlib import Path
import csv
import hashlib
import subprocess
import sys
import tempfile
import zipfile

with tempfile.TemporaryDirectory() as directory:
    root = Path(directory)
    wheel = root / "sample_wheel_demo-1.0-py3-none-any.whl"
    dist_info = "sample_wheel_demo-1.0.dist-info"

    files = {
        "sample_wheel_demo.py": "message = 'wheel installed'\n",
        f"{dist_info}/METADATA": (
            "Metadata-Version: 2.1\n"
            "Name: sample-wheel-demo\n"
            "Version: 1.0\n\n"
        ),
        f"{dist_info}/WHEEL": (
            "Wheel-Version: 1.0\n"
            "Generator: example\n"
            "Root-Is-Purelib: true\n"
            "Tag: py3-none-any\n"
        ),
    }
    record_path = f"{dist_info}/RECORD"
    with zipfile.ZipFile(wheel, "w") as archive:
        for name, contents in files.items():
            archive.writestr(name, contents)
        rows = []
        for name, contents in files.items():
            digest = hashlib.sha256(contents.encode()).digest()
            import base64
            encoded = base64.urlsafe_b64encode(digest).rstrip(b"=").decode()
            rows.append((name, f"sha256={encoded}", str(len(contents.encode()))))
        rows.append((record_path, "", ""))
        import io
        record = io.StringIO()
        csv.writer(record, lineterminator="\n").writerows(rows)
        archive.writestr(record_path, record.getvalue())

    target = root / "installed"
    result = subprocess.run(
        [sys.executable, "-m", "pip", "install", "--no-index", "--no-deps",
         "--target", str(target), str(wheel)],
        capture_output=True, text=True,
    )
    if result.returncode == 0:
        print("Installed sample-wheel-demo 1.0")
    else:
        print("Installation failed:", result.stderr.strip())
        raise SystemExit(result.returncode)

Dieses eigenständige Beispiel erstellt in einem temporären Verzeichnis ein kleines Wheel und lässt pip des aktuellen Interpreters in einem separaten Zielverzeichnis installieren. Bei einem vorhandenen Wheel lautet das Befehlsmuster python -m pip install "/path/to/package.whl". Durch Anführungszeichen funktionieren auch Pfade mit Leerzeichen in Verzeichnis- oder Dateinamen. Unter Windows können Sie einen Pfad wie "C:\Users\Ada\Downloads\package.whl" verwenden. In PowerShell und der Eingabeaufforderung funktioniert dieselbe Schreibweise mit Anführungszeichen.

Die Beispielausgabe zeigt Meldungen auf Englisch; sie bleiben unverändert. Wenn Sie das Wheel und seine Abhängigkeiten für eine Offline-Installation heruntergeladen haben, geben Sie pip das Verzeichnis mit den Dateien an: python -m pip install --no-index --find-links "/path/to/wheels" "/path/to/package.whl". Ohne diese lokalen Abhängigkeitsdateien kann pip im Offline-Betrieb keine Abhängigkeiten herunterladen.

Installationsfehler beheben

• Keine passende Distribution oder ein nicht unterstütztes Wheel-Tag: Prüfen Sie, ob die Python-, ABI- und Plattform-Tags des Wheels zu Interpreter und Rechner passen. Laden Sie einen passenden Build vom Publisher herunter oder folgen Sie dessen Anweisungen für eine andere unterstützte Installationsmethode.
• Eine Abhängigkeit fehlt: Lesen Sie die pip-Fehlermeldung, um die Abhängigkeit zu ermitteln. Installieren Sie zusätzlich ein kompatibles Abhängigkeits-Wheel oder lassen Sie pip die Abhängigkeit bei bestehender Internetverbindung aus dem konfigurierten Paketindex auflösen. Für eine Offline-Installation müssen alle benötigten Abhängigkeits-Wheels im lokalen Verzeichnis liegen.
• Das Paket ist installiert, lässt sich aber nicht importieren: Vergleichen Sie python -m pip --version mit dem Interpreter, mit dem Sie Ihre Anwendung ausführen. Verwenden Sie für beide denselben Interpreter oder aktivieren Sie vor der Installation die richtige virtuelle Umgebung.
• Zugriff verweigert: Verwenden Sie möglichst eine virtuelle Umgebung, über die Sie verfügen. Eine Installation auf Benutzerebene mit python -m pip install --user ... kann für einen Systeminterpreter geeignet sein. Manche verwalteten Umgebungen deaktivieren diese Option; richten Sie sich dort nach den Vorgaben der zuständigen Administration.
• Der Befehl pip wurde nicht gefunden: Rufen Sie pip mit python -m pip oder python3 -m pip auf. Falls dabei gemeldet wird, dass pip nicht verfügbar ist, folgen Sie der dokumentierten Anleitung Ihrer Python-Distribution, um pip für diesen Interpreter einzurichten.
• Ein Git-Repository enthält ein Wheel: Beim Klonen werden lediglich die darin versionierten Dateien heruntergeladen. Dadurch wird kein Paket installiert und es ist nicht gewährleistet, dass ein kompatibles Wheel vorhanden ist. Folgen Sie den Anweisungen der Projektverantwortlichen, suchen Sie nach einem veröffentlichten Wheel und installieren Sie diese lokale Datei mit pip. Beachten Sie bei Repository-Code und heruntergeladenen Artefakten die Vertrauens- und Prüfverfahren für deren Quelle.

Nutzen Sie bei einem Fehler die vollständige pip-Meldung, um festzustellen, ob das ausgewählte Wheel, eine Abhängigkeit, die Python-Umgebung oder Berechtigungen die Ursache sind. Beheben Sie das Problem und führen Sie die Installation anschließend mit dem vorgesehenen Interpreter erneut aus.