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.
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.txtque 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
cp314significa CPython 3.14, ou seja, Python 3.14;win_amd64significa 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
0
Não gosto
0
Adoro
0
Divertido
0
Irritado
0
Triste
0
Uau
0