Como instalar um pacote Python a partir de um arquivo .whl

Para instalar um arquivo Python .whl, escolha um wheel compatível com o interpretador Python e a plataforma que você usa e, em seguida, execute python -m pip install "/path/to/package.whl" no terminal. O pacote será instalado no ambiente associado a esse comando python. Um wheel é uma distribuição de pacote pronta para instalação; normalmente, você o instala com pip em vez de extraí-lo manualmente.

Entenda os arquivos .whl

Wheel é um formato de distribuição compilada para pacotes Python. Trata-se de um arquivo baseado em ZIP que contém arquivos do pacote e metadados organizados de uma forma reconhecida pelas ferramentas de instalação. Um wheel pode conter código Python, extensões compiladas ou ambos. Ao instalar um wheel compatível, geralmente não é necessário compilar o pacote a partir do código-fonte na sua máquina.

O nome do arquivo identifica a distribuição, a versão e as tags de compatibilidade, e vem seguido da extensão .whl. Essas tags descrevem, por exemplo, a implementação e a versão do Python, a interface binária de aplicativos (ABI) e o sistema operacional ou a plataforma do processador. Em geral, um wheel com a tag py3-none-any destina-se ao Python 3 e não inclui componentes binários específicos de uma plataforma; outros wheels podem ser limitados a determinadas versões do Python ou sistemas.

Escolha um wheel compatível

Obtenha o arquivo com o responsável pelo pacote ou em um índice de pacotes em que você confia. Antes de baixar, consulte as instruções de instalação do pacote e escolha um wheel cujas tags correspondam ao interpretador Python e à máquina em que você pretende instalá-lo. Um arquivo criado para outro sistema operacional, arquitetura de processador ou ABI do Python pode não funcionar, mesmo que o nome do pacote esteja correto.

Para verificar a qual interpretador um comando se refere, execute python --version e python -m pip --version. Em sistemas nos quais o comando do Python 3 é python3, use python3 de forma consistente. Se você tiver várias instalações do Python ou um ambiente virtual, ative primeiro o ambiente desejado ou use diretamente o caminho do interpretador correspondente. Assim, você evita instalar o pacote em um ambiente e tentar importá-lo de outro.

Um wheel local é útil quando a máquina de destino tem acesso limitado ou nenhum acesso à internet. Em uma máquina conectada, baixe o wheel e os wheels de todas as dependências necessárias, transfira-os para a máquina de destino e instale os arquivos locais. As opções --no-index e --find-links permitem que o pip procure dependências em um diretório local; elas não disponibilizam automaticamente os arquivos que estiverem faltando.

Instale um arquivo .whl com pip

Use python -m pip para executar o pip associado ao interpretador indicado por python. Substitua o caminho de exemplo pelo local e pelo nome do seu 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 exemplo independente cria um wheel pequeno em um diretório temporário e pede ao pip do interpretador atual que o instale em um diretório de destino separado. Para instalar um wheel existente, use o padrão de comando python -m pip install "/path/to/package.whl". Colocar o caminho entre aspas permite usar espaços nos nomes de diretórios ou arquivos. No Windows, use um caminho como "C:\Users\Ada\Downloads\package.whl"; o mesmo formato de argumento entre aspas funciona no PowerShell e no Prompt de Comando. As mensagens exibidas pelo exemplo permanecem em inglês.

Se você baixou o wheel e suas dependências para usar sem conexão, indique ao pip o diretório que contém esses arquivos: python -m pip install --no-index --find-links "/path/to/wheels" "/path/to/package.whl". Sem os arquivos locais das dependências, o pip não consegue baixá-las quando não há conexão.

Solucione erros de instalação

• Nenhuma distribuição compatível encontrada ou tag de wheel incompatível: confira se as tags de Python, ABI e plataforma do wheel correspondem ao interpretador e à máquina. Baixe uma versão compatível com o responsável pelo pacote ou siga as instruções dele para usar outra forma de instalação compatível.
• Falta uma dependência: leia a mensagem de erro do pip para identificar qual dependência está faltando. Instale também um wheel compatível dessa dependência ou, se houver acesso à internet, deixe que o pip a encontre no índice de pacotes configurado. Para uma instalação offline, inclua no diretório local todos os wheels necessários das dependências.
• O pacote é instalado, mas não pode ser importado: compare o resultado de python -m pip --version com o interpretador usado para executar seu aplicativo. Use o mesmo interpretador para ambos ou ative o ambiente virtual correto antes da instalação.
• Permissão negada: prefira um ambiente virtual que pertença a você. Uma instalação no nível do usuário com python -m pip install --user ... pode ser adequada para um interpretador do sistema, mas alguns ambientes gerenciados desativam essa opção; nesse caso, siga as orientações do administrador do ambiente.
• O comando pip não foi encontrado: invoque o pip com python -m pip ou python3 -m pip. Se isso indicar que o pip não está disponível, consulte as instruções documentadas da distribuição Python para configurar o pip nesse interpretador.
• Um repositório Git contém um wheel: clonar o repositório apenas baixa os arquivos rastreados; isso não instala um pacote nem garante que haja um wheel compatível. Siga as instruções de manutenção do projeto, localize um wheel publicado e instale esse arquivo local com pip. Siga as práticas de confiança e verificação da fonte ao lidar com código do repositório e arquivos baixados.

Se ocorrer uma falha, use a mensagem completa do pip para identificar se o problema está no wheel escolhido, em uma dependência, no ambiente Python ou nas permissões. Resolva a causa e execute novamente a instalação com o interpretador desejado.