Erro do pip «Microsoft Visual C++ 14.0 or greater is required»: soluções

Porque é que o pip pede o Microsoft Visual C++ ao instalar uma biblioteca Python e como resolver o erro, muitas vezes sem instalar nenhum compilador.

Erro do pip «Microsoft Visual C++ 14.0 or greater is required»: soluções

Está a instalar uma biblioteca Python com o pip e, depois de algumas linhas de progresso, o terminal enche-se de mensagens vermelhas que terminam mais ou menos assim:

error: Microsoft Visual C++ 14.0 or greater is required. Get it with "Microsoft C++ Build Tools": https://visualstudio.microsoft.com/visual-cpp-build-tools/
      [end of output]
  ERROR: Failed building wheel for nome-biblioteca
Failed to build nome-biblioteca

A mensagem sugere instalar as ferramentas de desenvolvimento C++ da Microsoft: vários gigabytes de software. Na maioria dos casos, porém, essa não é a melhor solução. Neste artigo vemos o que o erro significa realmente, como descobrir a causa e como resolvê-lo, começando pelas soluções mais simples.

O que significa o erro

Muitas bibliotecas Python contêm partes escritas em linguagem C, para serem mais rápidas. Esse código tem de ser compilado, ou seja, transformado num programa que o computador consegue executar. Os autores das bibliotecas costumam fazê-lo por si e publicam no PyPI, o arquivo oficial das bibliotecas Python, pacotes já prontos chamados wheels.

O ponto-chave é que uma wheel com código compilado só serve para:

  • uma versão específica do Python, por exemplo a 3.14;
  • um sistema operativo e um processador específicos, por exemplo Windows de 64 bits.

Quando o pip não encontra uma wheel adequada à sua combinação, descarrega o código-fonte e tenta compilá-lo sozinho. No Windows, para isso precisa do compilador C++ da Microsoft: se não existir, aparece o erro. Por outras palavras, a mensagem não quer dizer «falta-lhe o Visual C++», mas sim «não existe um pacote pronto para a sua configuração».

As causas mais comuns

  • Uma versão do Python demasiado recente. É a causa mais frequente. Quando sai uma nova versão, como o Python 3.15 a 9 de outubro de 2026, muitas bibliotecas demoram semanas ou meses a publicar wheels compatíveis. Entretanto, o pip tenta compilar.
  • Uma versão do Python demasiado antiga. O caso oposto: as versões recentes de uma biblioteca deixam de publicar wheels para versões do Python sem suporte.
  • Uma versão da biblioteca antiga ou fixada no projeto. Um ficheiro requirements.txt que impõe uma versão desatualizada de uma biblioteca pode não ter wheels para o seu Python.
  • Um processador ou um sistema menos comum, por exemplo Windows em ARM ou Python de 32 bits.
  • Uma dependência indireta. Por vezes a biblioteca que falha não é a que pediu, mas uma que ela traz consigo.

Como perceber qual é a biblioteca que falha

Leia o resultado a partir do início: procure as linhas que começam por Building wheel for ou Failed building wheel for. O nome que aparece aí é a biblioteca que o pip está a tentar compilar. Muitas vezes não é a que instalou: por exemplo, ao pedir uvicorn[standard], o pip instala também outras bibliotecas opcionais, e uma delas pode ser a que não tem wheel.

Depois verifique que versão do Python está a usar:

python --version

Como verificar se existe uma wheel para o seu Python

Abra a página da biblioteca em pypi.org e clique em Download files. Os nomes dos ficheiros contêm siglas que indicam para que configuração foram preparados. Por exemplo:

nomebiblioteca-1.2.0-cp314-cp314-win_amd64.whl
  • cp314 significa CPython 3.14, ou seja, Python 3.14;
  • win_amd64 significa Windows de 64 bits.

Se na lista não houver nenhum ficheiro para a sua versão (por exemplo cp315 se usa o Python 3.15), encontrou a causa.

Solução 1: atualizar o pip

É a primeira coisa a fazer, porque demora poucos segundos: uma versão antiga do pip pode não reconhecer as wheels mais recentes.

python -m pip install --upgrade pip

Depois repita a instalação da biblioteca.

Solução 2: usar uma versão do Python suportada

Se a biblioteca ainda não tem wheels para a sua versão do Python, a solução mais limpa é usar a versão anterior. Com o Python Install Manager no Windows bastam poucos comandos:

py install 3.14

Depois recrie o ambiente virtual do projeto com essa versão. A partir da pasta do projeto:

rmdir /s /q .venv
py -V:3.14 -m venv .venv
.venv\Scripts\activate
python -m pip install -r requirements.txt

O primeiro comando apaga o ambiente antigo; os outros recriam-no com o Python 3.14 e reinstalam as bibliotecas. Pode manter as duas versões do Python instaladas e usar a mais recente nos outros projetos.

Esta é a solução certa na grande maioria dos casos: em poucos minutos resolve o problema sem instalar nada pesado.

Solução 3: atualizar a biblioteca

Se no projeto estiver indicada uma versão exata da biblioteca, por exemplo nomebiblioteca==1.0.3 no ficheiro requirements.txt, experimente uma versão mais recente, que pode ter wheels para o seu Python:

python -m pip install --upgrade nomebiblioteca

Verifique depois se o seu programa continua a funcionar: uma nova versão principal de uma biblioteca pode trazer alterações.

Solução 4: evitar as dependências opcionais

Algumas bibliotecas oferecem «extras» opcionais, indicados entre parênteses retos, como uvicorn[standard]. Se a biblioteca que falha vem de um destes extras e não precisa dele, instale a versão base:

python -m pip install uvicorn

Solução 5: pedir ao pip que use apenas wheels

Com esta opção o pip nunca tenta compilar: se existir uma versão da biblioteca com uma wheel compatível, escolhe-a; caso contrário, para logo com uma mensagem clara, em vez de um longo erro de compilação.

python -m pip install --only-binary :all: nomebiblioteca

Também é útil como ferramenta de diagnóstico: diz-lhe com certeza se o problema é a falta de wheels.

Solução 6: instalar os Microsoft C++ Build Tools

Se nenhuma das soluções anteriores funcionar, por exemplo porque precisa mesmo de uma biblioteca que não publica wheels para Windows, pode instalar o compilador. É a solução sugerida pela mensagem de erro:

  • Descarregue os Microsoft C++ Build Tools a partir da página indicada no erro.
  • Durante a instalação selecione a carga de trabalho Desenvolvimento de desktop com C++ («Desktop development with C++»), que inclui o compilador MSVC e o Windows SDK.
  • No fim, reinicie o computador, abra um novo terminal, ative o ambiente virtual e repita a instalação.

Tenha em conta que a instalação ocupa vários gigabytes e que algumas bibliotecas exigem, além do compilador, outros componentes específicos indicados na sua documentação.

E no Linux?

No Linux o erro tem um aspeto diferente, normalmente com mensagens sobre o gcc ou sobre ficheiros como Python.h, mas a causa é a mesma. As soluções 1–5 também se aplicam aqui. Se for mesmo preciso compilar, no Ubuntu e no Debian instale as ferramentas básicas:

sudo apt install build-essential python3-dev

Em resumo

  • O erro significa que não existe um pacote pronto para a sua combinação de Python e sistema operativo.
  • A causa mais frequente é uma versão do Python demasiado recente.
  • A solução mais rápida é atualizar o pip e, se não bastar, usar a versão anterior do Python num novo ambiente virtual.
  • Os Build Tools são o último recurso, não o primeiro.

Fontes oficiais

Partilhar

Qual é a sua reação?

Gosto Gosto 0
Não gosto Não gosto 0
Adoro Adoro 0
Divertido Divertido 0
Irritado Irritado 0
Triste Triste 0
Uau Uau 0