Comment installer un paquet Python au format .whl

Pour installer un fichier Python .whl, choisissez une wheel compatible avec votre interpréteur Python et votre plateforme, puis exécutez python -m pip install "/path/to/package.whl" dans un terminal. Le paquet sera installé dans l’environnement associé à cette commande python. Une wheel est une distribution prête à être installée ; en général, vous l’installez avec pip au lieu de la décompresser vous-même.

Comprendre les fichiers .whl

Une wheel est un format de distribution compilée pour les paquets Python. Il s’agit d’une archive basée sur ZIP qui contient les fichiers du paquet et ses métadonnées dans une structure comprise par les outils d’installation. Une wheel peut contenir du code Python, des extensions compilées, ou les deux. Installer une wheel compatible permet généralement d’éviter de compiler le paquet à partir de ses sources sur votre machine.

Le nom du fichier indique la distribution, sa version et ses balises de compatibilité ; il est suivi de l’extension .whl. Ces balises décrivent notamment l’implémentation et la version de Python, l’interface binaire applicative (ABI), ainsi que le système d’exploitation ou la plateforme du processeur. Une wheel marquée py3-none-any est généralement destinée à Python 3 et ne contient pas de composant binaire propre à une plateforme ; d’autres wheels peuvent être limitées à certaines compilations de Python ou à certains systèmes.

Choisir une wheel compatible

Obtenez le fichier auprès de l’éditeur du paquet ou d’un index de paquets auquel vous faites confiance. Avant le téléchargement, consultez les instructions d’installation du paquet et choisissez une wheel dont les balises correspondent à l’interpréteur Python et à la machine sur lesquels vous comptez l’installer. Un fichier conçu pour un autre système d’exploitation, une autre architecture de processeur ou une autre ABI Python peut être inutilisable, même si le nom du paquet est correct.

Pour savoir à quel interpréteur une commande fait référence, exécutez python --version et python -m pip --version. Sur les systèmes où la commande Python 3 est python3, utilisez python3 de manière cohérente. Si plusieurs installations de Python ou un environnement virtuel sont disponibles, activez d’abord l’environnement voulu ou indiquez directement le chemin de son interpréteur. Vous éviterez ainsi d’installer le paquet dans un environnement, puis d’essayer de l’importer depuis un autre.

Une wheel locale est utile lorsque la machine cible dispose d’un accès Internet limité ou inexistant. Sur une machine connectée, téléchargez la wheel ainsi que toutes les wheels de dépendances nécessaires, transférez-les vers la machine cible, puis installez les fichiers locaux. Les options --no-index et --find-links indiquent à pip de chercher les dépendances dans un répertoire local ; elles ne fournissent pas automatiquement les dépendances manquantes.

Installer un fichier .whl avec pip

Utilisez python -m pip pour que pip s’exécute avec l’interpréteur désigné par python. Remplacez le chemin d’exemple par l’emplacement et le nom de votre wheel :

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)

Cet exemple autonome crée une petite wheel dans un répertoire temporaire, puis demande à pip, lancé par l’interpréteur courant, de l’installer dans un autre répertoire cible. Pour installer une wheel existante, utilisez la forme de commande python -m pip install "/path/to/package.whl". Les guillemets permettent de gérer les espaces dans les noms de répertoires ou de fichiers. Sous Windows, indiquez un chemin tel que "C:\Users\Ada\Downloads\package.whl" ; la même forme d’argument entre guillemets fonctionne dans PowerShell et dans l’invite de commandes. Les messages affichés par l’exemple restent en anglais.

Si vous avez téléchargé la wheel et ses dépendances pour une utilisation hors ligne, indiquez à pip le répertoire qui les contient : python -m pip install --no-index --find-links "/path/to/wheels" "/path/to/package.whl". Sans ces fichiers de dépendances locaux, pip ne peut pas les récupérer hors ligne.

Résoudre les erreurs d’installation

• Aucune distribution correspondante ou balise de wheel non prise en charge : Vérifiez que les balises Python, ABI et plateforme de la wheel sont compatibles avec l’interpréteur et la machine. Téléchargez une version compatible auprès de l’éditeur ou suivez ses instructions pour une autre méthode d’installation prise en charge.
• Une dépendance est manquante : Consultez le message d’erreur de pip pour identifier la dépendance. Installez également une wheel compatible pour cette dépendance ou, si vous avez accès à Internet, laissez pip la récupérer depuis l’index de paquets configuré. Pour une installation hors ligne, placez toutes les wheels de dépendances nécessaires dans le répertoire local.
• Le paquet est installé, mais ne peut pas être importé : Comparez python -m pip --version avec l’interpréteur utilisé pour exécuter votre application. Utilisez le même interpréteur pour les deux opérations ou activez le bon environnement virtuel avant l’installation.
• Accès refusé : Privilégiez un environnement virtuel dont vous êtes propriétaire. Une installation au niveau de l’utilisateur avec python -m pip install --user ... peut convenir à un interpréteur système, mais certains environnements gérés désactivent cette option ; suivez alors les consignes de leur administrateur.
• La commande pip est introuvable : Lancez pip avec python -m pip ou python3 -m pip. Si cette commande indique que pip n’est pas disponible, suivez les instructions documentées de la distribution Python pour configurer pip avec cet interpréteur.
• Un dépôt Git contient une wheel : Le clonage du dépôt ne fait que télécharger les fichiers qu’il suit ; il n’installe pas de paquet et ne garantit pas la présence d’une wheel compatible. Suivez les instructions du responsable du projet, repérez une wheel publiée, puis installez ce fichier local avec pip. Traitez le code du dépôt et les artefacts téléchargés conformément aux pratiques de confiance et de vérification de leur source.

En cas d’échec, lisez l’intégralité du message de pip pour déterminer si le problème vient de la wheel choisie, d’une dépendance, de l’environnement Python ou des permissions. Corrigez la cause, puis relancez l’installation avec l’interpréteur voulu.