Cómo instalar un paquete de Python desde un archivo .whl

Para instalar un archivo Python .whl, elige una wheel compatible con tu intérprete de Python y tu plataforma; después, ejecuta python -m pip install "/path/to/package.whl" en una terminal. El paquete se instalará en el entorno asociado al comando python utilizado. Una wheel es una distribución de paquete lista para instalar; normalmente se instala con pip, en lugar de descomprimirla manualmente.

Qué son los archivos .whl

Una wheel es un formato de distribución compilada para paquetes de Python. Es un archivo basado en ZIP que contiene los archivos del paquete y sus metadatos organizados de una forma que las herramientas de instalación pueden interpretar. Puede incluir código Python, extensiones compiladas o ambos. Instalar una wheel compatible suele evitar que tengas que compilar el paquete desde el código fuente en tu equipo.

El nombre del archivo identifica la distribución, la versión y las etiquetas de compatibilidad; a continuación aparece la extensión .whl. Estas etiquetas describen, entre otros datos, la implementación y la versión de Python, la interfaz binaria de la aplicación (ABI) y la plataforma del sistema operativo o del procesador. Por lo general, una wheel marcada como py3-none-any está destinada a Python 3 y no incluye componentes binarios específicos de una plataforma; otras wheels pueden estar limitadas a determinadas compilaciones de Python o sistemas.

Elegir una wheel compatible

Obtén el archivo del editor del paquete o de un índice de paquetes de confianza. Antes de descargarlo, consulta las instrucciones de instalación del paquete y elige una wheel cuyas etiquetas coincidan con el intérprete de Python y el equipo donde planeas instalarla. Un archivo creado para otro sistema operativo, arquitectura de procesador o ABI de Python podría no ser compatible, aunque el nombre del paquete sea correcto.

Para saber a qué intérprete corresponde un comando, ejecuta python --version y python -m pip --version. En los sistemas donde el comando para Python 3 es python3, úsalo de forma consistente. Si tienes varias instalaciones de Python o un entorno virtual, activa primero el entorno deseado o indica directamente la ruta a su intérprete. Así evitarás instalar el paquete en un entorno e intentar importarlo desde otro.

Una wheel local resulta útil cuando el equipo de destino tiene acceso limitado a Internet o no tiene conexión. Descarga en un equipo conectado la wheel y cualquier otra wheel necesaria para sus dependencias, transfiere los archivos al equipo de destino e instala desde allí. Las opciones --no-index y --find-links indican a pip que busque dependencias en un directorio local; no proporcionan automáticamente las dependencias que falten.

Instalar un archivo .whl con pip

Usa python -m pip para que pip se ejecute con el intérprete indicado por python. Sustituye la ruta de ejemplo por la ubicación y el nombre de tu 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)

Este ejemplo autónomo crea una wheel pequeña en un directorio temporal y pide al pip del intérprete actual que la instale en un directorio de destino independiente. Para una wheel que ya tengas, el patrón del comando es python -m pip install "/path/to/package.whl". Las comillas permiten usar rutas con espacios en los nombres de directorios o archivos. En Windows, puedes usar una ruta como "C:\Users\Ada\Downloads\package.whl"; en PowerShell y en el Símbolo del sistema también funciona el mismo formato de argumento entre comillas. Los mensajes que muestra el ejemplo permanecen en inglés.

Si descargaste la wheel y sus dependencias para usarlas sin conexión, indica a pip el directorio donde están: python -m pip install --no-index --find-links "/path/to/wheels" "/path/to/package.whl". Si esos archivos de dependencias no están disponibles localmente, pip no podrá descargarlos mientras no haya conexión.

Solucionar errores de instalación

• No hay una distribución coincidente o la etiqueta de la wheel no es compatible: Comprueba que las etiquetas de Python, ABI y plataforma de la wheel sean compatibles con el intérprete y el equipo. Descarga una compilación adecuada del editor o sigue sus instrucciones para usar otra forma de instalación compatible.
• Falta una dependencia: Lee el mensaje de error de pip para identificarla. Instala también una wheel compatible para esa dependencia o, si tienes conexión, deja que pip la resuelva desde el índice de paquetes configurado. Para instalar sin conexión, incluye en el directorio local todas las wheels necesarias para las dependencias.
• El paquete se instala, pero no se puede importar: Compara el resultado de python -m pip --version con el intérprete que usas para ejecutar tu aplicación. Usa el mismo intérprete para ambos comandos o activa el entorno virtual correcto antes de instalar.
• Se deniega el permiso: Es preferible usar un entorno virtual que esté bajo tu control. Una instalación para el usuario mediante python -m pip install --user ... puede ser adecuada para un intérprete del sistema, pero algunos entornos administrados desactivan esta opción; en esos casos, sigue las indicaciones del administrador del entorno.
• No se encuentra el comando pip: Ejecuta pip como python -m pip o python3 -m pip. Si el comando indica que pip no está disponible, consulta las instrucciones documentadas de la distribución de Python para configurar pip en ese intérprete.
• Un repositorio de Git contiene una wheel: Clonar el repositorio solo descarga los archivos que tiene bajo seguimiento; no instala un paquete ni garantiza que incluya una wheel compatible. Sigue las instrucciones de mantenimiento del proyecto, busca una wheel publicada e instala ese archivo local con pip. Aplica las prácticas de confianza y verificación correspondientes al código del repositorio y a los archivos descargados.

Ante cualquier fallo, usa el mensaje completo de pip para determinar si el problema está en la wheel seleccionada, una dependencia, el entorno de Python o los permisos. Corrige la causa y vuelve a ejecutar la instalación con el intérprete previsto.