Come installare un pacchetto Python da un file .whl

Per installare un file Python .whl, scegli un wheel compatibile con l’interprete Python e la piattaforma in uso, quindi esegui da un terminale python -m pip install "/path/to/package.whl". Il pacchetto verrà installato nell’ambiente associato a quel comando python. Un wheel è una distribuzione pronta per l’installazione: di norma si installa con pip, senza estrarne manualmente i file.

Che cosa sono i file .whl

Un wheel è un formato di distribuzione compilato per i pacchetti Python. È un archivio basato su ZIP che contiene i file del pacchetto e i metadati in una struttura riconosciuta dagli strumenti di installazione. Può includere codice Python, estensioni compilate o entrambi. Installare un wheel compatibile in genere evita di compilare il pacchetto dal codice sorgente sul proprio computer.

Il nome del file identifica la distribuzione, la versione e i tag di compatibilità; dopo il nome compare l’estensione .whl. I tag indicano, tra le altre cose, l’implementazione e la versione di Python, l’interfaccia binaria dell’applicazione (ABI) e il sistema operativo o la piattaforma del processore. In genere un wheel contrassegnato py3-none-any è destinato a Python 3 e non contiene componenti binari specifici per una piattaforma; altri wheel possono essere limitati a determinate build di Python o a specifici sistemi.

Scegliere un wheel compatibile

Scarica il file dal produttore del pacchetto o da un indice di pacchetti di cui ti fidi. Prima di scaricarlo, consulta le istruzioni di installazione del pacchetto e scegli un wheel con tag compatibili con l’interprete Python e il computer su cui vuoi installarlo. Un file creato per un altro sistema operativo, un’altra architettura del processore o un’ABI Python diversa potrebbe non essere utilizzabile, anche se il nome del pacchetto è corretto.

Per verificare a quale interprete fa riferimento un comando, esegui python --version e python -m pip --version. Nei sistemi in cui il comando per Python 3 è python3, usa python3 in modo coerente. Se hai più installazioni di Python o un ambiente virtuale, attiva prima l’ambiente desiderato oppure usa direttamente il percorso del relativo interprete. Così eviti di installare il pacchetto in un ambiente e poi tentare di importarlo da un altro.

Un wheel locale è utile quando il computer di destinazione ha accesso a Internet limitato o assente. Su un computer connesso, scarica il wheel e tutti i wheel delle dipendenze necessarie, trasferiscili sul computer di destinazione e installa dai file locali. Le opzioni --no-index e --find-links indicano a pip di cercare le dipendenze in una directory locale, ma non rendono automaticamente disponibili quelle mancanti.

Installare un file .whl con pip

Usa python -m pip per eseguire pip con l’interprete indicato da python. Sostituisci il percorso di esempio con la posizione e il nome del tuo 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)

Questo esempio autonomo crea un piccolo wheel in una directory temporanea e chiede a pip dell’interprete corrente di installarlo in una directory di destinazione separata. Per un wheel esistente, il comando ha questa forma: python -m pip install "/path/to/package.whl". Racchiudere il percorso tra virgolette permette di gestire spazi nei nomi delle directory o dei file. In Windows, usa un percorso come "C:\Users\Ada\Downloads\package.whl"; in PowerShell e nel Prompt dei comandi funziona la stessa forma con l’argomento tra virgolette. L’esempio mostra messaggi in inglese, che restano in inglese anche nell’articolo italiano.

Se hai scaricato il wheel e le sue dipendenze per un’installazione offline, indica a pip la directory che li contiene: python -m pip install --no-index --find-links "/path/to/wheels" "/path/to/package.whl". Senza i file locali delle dipendenze, pip non può scaricarle quando sei offline.

Risolvere gli errori di installazione

• Nessuna distribuzione corrispondente o tag del wheel non supportato: verifica che i tag Python, ABI e piattaforma del wheel siano compatibili con l’interprete e il computer. Scarica una build compatibile dal produttore oppure segui le istruzioni per un’altra modalità di installazione supportata.
• Manca una dipendenza: leggi il messaggio di errore di pip per individuare la dipendenza. Installa anche un wheel compatibile per quella dipendenza oppure, se hai accesso a Internet, lascia che pip la risolva tramite l’indice di pacchetti configurato. Per un’installazione offline, includi nella directory locale tutti i wheel delle dipendenze necessarie.
• Il pacchetto si installa ma non può essere importato: confronta python -m pip --version con l’interprete usato per eseguire l’applicazione. Esegui entrambi tramite lo stesso interprete oppure attiva l’ambiente virtuale corretto prima dell’installazione.
• Accesso negato: preferisci un ambiente virtuale di cui sei proprietario. Un’installazione a livello utente con python -m pip install --user ... può essere adatta a un interprete di sistema, ma alcuni ambienti gestiti non la consentono; in tal caso segui le indicazioni dell’amministratore dell’ambiente.
• Il comando pip non viene trovato: avvia pip con python -m pip o python3 -m pip. Se il comando segnala che pip non è disponibile, segui le istruzioni documentate per configurare pip nella distribuzione Python di quell’interprete.
• Un repository Git contiene un wheel: clonare il repository scarica soltanto i file tracciati; non installa un pacchetto e non garantisce che sia presente un wheel compatibile. Segui le istruzioni del manutentore del progetto, individua un wheel pubblicato e installa quel file locale con pip. Applica ai repository e agli artefatti scaricati le pratiche di fiducia e verifica appropriate per la loro provenienza.

In caso di errore, leggi per intero il messaggio di pip per capire se il problema riguarda il wheel scelto, una dipendenza, l’ambiente Python o i permessi. Risolvi la causa e ripeti l’installazione con l’interprete desiderato.