Como instalar o scikit-learn (todos os métodos)

O nosso interesse nesta questão é praticamente nulo: somos a Geonode e vendemos proxies, o que não tem nada a ver com a instalação de uma biblioteca Python. O único ponto em que se cruzam merece uma menção — se o comando «pip install» ficar bloqueado num ambiente empresarial, isso significa, normalmente, que a sua rede requer um proxy que o pip desconhece, e a solução é «pip install --proxy» ou as variáveis de ambiente padrão. Esse caso é abordado no final. Tudo o resto aqui não requer infraestrutura nem qualquer compra.

A resposta curta

python -m venv sklearn-env
source sklearn-env/bin/activate          # Windows: sklearn-env\Scripts\activate
pip install -U scikit-learn

Ou com o conda:

conda create -n sklearn-env -c conda-forge scikit-learn
conda activate sklearn-env

A documentação oficial apresenta ambas as opções e é enfática quanto ao ambiente: «o ambiente virtual é opcional, mas fortemente recomendado, para evitar potenciais conflitos com outros pacotes».

Acrescenta ainda um lembrete que apanha constantemente as pessoas de surpresa: «Deve lembrar-se sempre de ativar o ambiente da sua escolha antes de executar qualquer comando Python sempre que iniciar uma nova sessão de terminal.» Muitos dos relatos do tipo «ontem estava a funcionar» devem-se a um novo terminal sem o ambiente ativado.

Por que razão «pip install sklearn» falha

A pergunta mais comum nesta área, e a resposta é: trata-se de um design deliberado.

«sklearn» é o nome da importação. «scikit-learn» é o nome do pacote. Ao digitar o primeiro no pip, instala-se um marcador de lugar cujo único objetivo é impedir que o utilizador avance.

A própria descrição desse marcador de lugar no PyPI é inequívoca: «pacote sklearn obsoleto, utilize scikit-learn em vez disso», com a orientação para «utilizar pip install scikit-learn em vez de pip install sklearn» e para «substituir sklearn por scikit-learn nos seus ficheiros de requisitos do pip».

A razão para a sua existência é de natureza relacionada com a cadeia de abastecimento, claramente explicada na sua documentação:

O pacote sklearn no PyPI existe para impedir que agentes maliciosos utilizem o pacote sklearn, uma vez que sklearn (o nome de importação) e scikit-learn (o nome do projeto) são, por vezes, utilizados de forma intercambiável.

Por outras palavras, os responsáveis pelo pacote reivindicaram o nome que dá azo a confusão para que mais ninguém o pudesse fazer. Tendo em conta o número de pessoas que o digitam, foi uma medida sensata.

A documentação do pacote descreve três casos extremos que vale a pena conhecer, caso os encontre:

• «pip install sklearn==1.1.3 indicará que a versão 1.1.3 não existe, o que é confuso» — o placeholder tem apenas os seus próprios números de versão.
• «pip uninstall sklearn, na verdade, não desinstalará scikit-learn; ainda poderá executar import sklearn posteriormente».
• Ter ambos em pip list é confuso e normal se os tiver instalado acidentalmente.

Existe uma saída de emergência — definir SKLEARN_ALLOW_DEPRECATED_SKLEARN_PACKAGE_INSTALL=True — e é descrita como «um último recurso». Se se vir a recorrer a ela, a verdadeira solução é quase sempre uma dependência sua que inclua sklearn nos seus requisitos. Vale a pena seguir o próprio conselho do placeholder: «identifique qual o pacote que utiliza sklearn em vez de scikit-learn e comunique-o ao seu sistema de acompanhamento de problemas».

Nos seus próprios ficheiros, escreva sempre scikit-learn. No seu código, escreva sempre import sklearn. A assimetria é permanente.

Requisitos

De acordo com os metadados do pacote para a versão atual, verificados em setembro de 2026.

O scikit-learn 1.9.0 foi publicado a 2 de junho de 2026 e requer o Python 3.11 ou posterior.

As suas dependências de execução:

Duas notas sobre esta tabela.

** O narwhals é uma adição relativamente recente** e não aparecerá na documentação mais antiga nem em tutoriais escritos com base em versões anteriores. Se estiver a fixar as dependências manualmente, em vez de deixar que o pip as resolva, esta é a que provavelmente irá deixar escapar.

Os requisitos do Python mudam. A tabela de dependências da página de instalação reflete a versão que está a ser documentada, e os requisitos têm vindo a aumentar nas versões mais recentes. Se estiver a utilizar uma versão mais antiga do Python, o pip irá resolver com uma versão mais antiga do scikit-learn em vez de falhar — o que normalmente não constitui um problema e, por vezes, explica a ausência de uma funcionalidade sobre a qual leu.

Existem extras opcionais declarados para benchmarking, documentação, exemplos e testes, que incluem o matplotlib, o pandas, o polars, o pyarrow e outros. Não precisa de nenhum deles para utilizar a biblioteca.

Instalação sem um ambiente virtual

Por vezes, pretende-se realmente uma instalação a nível do sistema, e há um aviso associado a isso.

A documentação é clara especificamente em relação ao Linux: «Em particular, no Linux, não é recomendável instalar pacotes pip juntamente com os pacotes geridos pelo gestor de pacotes da distribuição (apt, dnf, pacman…).»

A razão é que tanto o pip como o gestor de pacotes da sua distribuição consideram que são os proprietários dos ficheiros na pasta site-packages do Python do sistema e, quando entram em conflito, o resultado é uma instalação do Python que se comporta de forma estranha, de maneiras difíceis de resolver. Nas distribuições mais recentes, o pip recusa-se categoricamente, apresentando um erro de «ambiente gerido externamente», o que corresponde ao ecossistema de pacotes a impedir exatamente esta situação.

Se se deparar com esse erro, as opções, por ordem de preferência, são: utilizar um ambiente virtual, utilizar pipx para ferramentas de linha de comandos, utilizar o próprio pacote python3-sklearn da sua distribuição, caso exista, ou — sabendo o que está a fazer — anular com --break-system-packages, um sinalizador cujo nome foi escolhido para o dissuadir.

No macOS e no Windows, a pressão é menor, mas o conselho mantém-se. Criar um ambiente virtual por projeto demora dez segundos e evita toda uma categoria de problemas.

Verificar a instalação

A documentação fornece os comandos, e vale a pena dedicar trinta segundos a executá-los.

python -m pip show scikit-learn    # version and install location
python -m pip freeze              # everything in the environment
python -c "import sklearn; sklearn.show_versions()"

Com o conda:

conda list scikit-learn
conda list

sklearn.show_versions()

é o comando a utilizar quando se reporta um problema. Este comando apresenta a versão do scikit-learn, a versão e compilação do Python, bem como as versões da pilha numérica subjacente — que são precisamente as informações que qualquer responsável pela manutenção irá solicitar em primeiro lugar.

Vale a pena verificar o local de instalação em pip show

quando algo se comportar de forma estranha. Se apontar para um local diferente do ambiente em que pensa que se encontra, aí tem a sua resposta: import sklearn

irá localizar a instalação que aparecer primeiro no caminho, e essa pode não ser a que acabou de instalar.

conda versus pip

Ambos funcionam. A escolha é importante sobretudo se os estiver a utilizar em simultâneo, o que não deve fazer de ânimo leve.

Utilize o conda quando já tiver um ambiente conda, quando precisar de bibliotecas numéricas compiladas específicas ou quando estiver numa plataforma em que, de outra forma, seria necessário compilar a partir do código-fonte. Dê preferência ao conda-forge como canal, tal como indicam as instruções oficiais.

Utilize o pip quando estiver num ambiente virtual Python normal, o que abrange a maioria dos projetos. Os «wheels» são publicados para as plataformas mais comuns, pelo que nada precisa de ser compilado e a instalação demora apenas alguns segundos.

Não os misture num único ambiente sem pensar. Instalar um pacote com o conda e, em seguida, atualizar uma dependência com o pip cria um ambiente em que os metadados do conda já não refletem a realidade, e a falha resultante é difícil de diagnosticar. Se for necessário, instale primeiro tudo o que puder com o conda e só depois utilize o pip para o que o conda não tiver.

Existe uma forma prática de saber em que ambiente se encontra: se which python apontar para dentro de um diretório do ambiente conda, utilize o conda para esse ambiente.

Erros comuns após a instalação

ModuleNotFoundError: No module named 'sklearn' após uma instalação bem-sucedida. Quase sempre, o problema é o ambiente errado — um terminal diferente, um interpretador diferente ou um kernel do notebook a apontar para outro local. Verifique com:

import sys; print(sys.executable)

e compare com o ambiente em que efetuou a instalação. Especificamente no Jupyter, o kernel é uma escolha separada do ambiente do terminal, e a instalação num não tem qualquer efeito no outro. O comando %pip install scikit-learn dentro do notebook instala-se no ambiente do kernel, o que constitui a solução fiável.

ImportError mencionando o NumPy ou uma incompatibilidade binária. Normalmente, trata-se de uma incompatibilidade entre versões compiladas, na maioria das vezes causada pela atualização independente do NumPy. A reinstalação simultânea de ambos resolve o problema:

pip install --force-reinstall --no-cache-dir numpy scipy scikit-learn

Uma compilação que tenta compilar a partir do código-fonte. Isto significa que nenhum wheel correspondia à sua plataforma e versão do Python — geralmente uma versão muito recente do Python, antes da publicação dos wheels, ou uma arquitetura invulgar. Esperar algumas semanas ou utilizar uma versão ligeiramente mais antiga do Python é mais fácil do que instalar uma cadeia de ferramentas de compilação.

Tanto sklearn como scikit-learn em pip list. Instalou o marcador de lugar em algum momento. Removê-lo é seguro: pip uninstall sklearn. Conforme indicado na documentação, isto «na verdade não desinstalará o scikit-learn».

Avisos sobre threads ou threadpoolctl. O scikit-learn utiliza-o para gerir os conjuntos de threads das bibliotecas BLAS subjacentes. Definir explicitamente OMP_NUM_THREADS resolve a maioria destes problemas e vale a pena fazê-lo de qualquer forma em contentores, onde uma biblioteca sem restrições criará alegremente uma thread por CPU do anfitrião, independentemente do seu limite de CPU.

Fixação de versões para reprodutibilidade

A instalação é um processo único; manter a mesma instalação no mês seguinte é o problema mais difícil, e vale a pena preparar tudo antes de precisar disso.

Fixa as versões num ficheiro de requisitos, não na tua cabeça. Um simples ``pip install scikit-learn`

` hoje e o mesmo comando daqui a seis meses resultam em versões diferentes, e a API do scikit-learn muda entre versões secundárias — os estimadores ganham parâmetros, os valores por predefinição alteram-se e, ocasionalmente, algo é removido após um ciclo de descontinuação:

scikit-learn==1.9.0
numpy==2.3.1
scipy==1.16.0

Fixa também a pilha numérica, não apenas o scikit-learn. A maioria das falhas de reprodutibilidade neste ecossistema decorre do facto de o NumPy ou o SciPy se alterarem por baixo de um scikit-learn fixado, porque as interfaces compiladas entre eles são mais restritas do que os especificadores de versão sugerem. Fixar o topo da árvore e deixar o resto flutuar é a configuração com maior probabilidade de falhar.

Gere o ficheiro a partir de um ambiente de trabalho em vez de o escrever manualmente:

pip freeze > requirements.txt

Isso capta tudo, incluindo dependências transitivas, que é o que se pretende para uma aplicação. Para uma biblioteca que esteja a publicar, especifique intervalos e deixe que os utilizadores resolvam — uma biblioteca que fixa versões exatas torna-se impossível de combinar com qualquer outra coisa.

Registe as versões juntamente com os teus resultados. As saídas do modelo dependem da versão da biblioteca, e um modelo guardado não é portátil entre versões arbitrárias — despicklar um estimador guardado por uma versão diferente pode gerar avisos, falhar ou comportar-se de forma diferente sem aviso prévio. Armazenar uma saída dsklearn.show_versions()

o ao lado de qualquer modelo persistido transforma um mistério futuro numa simples consulta.

E desconfie dos modelos «pickled» como formato de armazenamento. Estes incorporam a estrutura de classe da versão que os criou, razão pela qual deixam de funcionar após atualizações, e executam código ao serem carregados — pelo que um «pickle» proveniente de uma fonte não fiável constitui a execução de código arbitrário, em vez de um ficheiro de dados. Para qualquer elemento de longa duração, opte por um formato concebido para intercâmbio ou, no mínimo, guarde o código de treino e os dados para que o modelo possa ser reconstruído.

Instalação através de um proxy empresarial

Este é o único caso em que o nosso tema é relevante e o sintoma é característico.

Se pip install

ficar bloqueado e, em seguida, atingir o tempo limite, em vez de falhar rapidamente com um erro de resolução de nomes, a sua rede provavelmente requer um proxy que o pip não reconhece.

pip install --proxy http://user:password@proxy.example.com:9000 scikit-learn

Ou através do ambiente, o que se aplica ao conda e à maioria das outras ferramentas também:

export https_proxy=http://user:password@proxy.example.com:9000
export http_proxy=http://user:password@proxy.example.com:9000

Há duas coisas que costumam correr mal aqui.

Os caracteres especiais na palavra-passe precisam de codificação por por cento. Um @

ou um :

num URL de proxy divide a cadeia de caracteres no local errado, produzindo uma falha de autenticação mesmo com credenciais corretas.

A interceção TLS interrompe a verificação do certificado. Os proxies empresariais frequentemente terminam a ligação TLS, e o pip rejeita então o certificado porque este foi emitido pela autoridade da sua organização, em vez de por uma autoridade pública. A solução correta é apontar o pip para o pacote de CA da sua organização:

pip config set global.cert /path/to/corporate-ca.pem

A solução tentadora é --trusted-host pypi.org

, que desativa a verificação para esse anfitrião. Compreenda o que isso implica antes de a utilizar: está a optar por aceitar qualquer certificado que seja apresentado para o servidor a partir do qual descarrega código executável.

Para o conda, a configuração equivalente encontra-se em .condarc

, em proxy_servers

e ssl_verify

.

Perguntas frequentes

Como instalo o scikit-learn?

pip install -U scikit-learn num ambiente virtual, ou conda create -n sklearn-env -c conda-forge scikit-learn com o conda. A documentação recomenda vivamente a utilização de um ambiente virtual para evitar conflitos com outros pacotes.

Por que é que a instalação do sklearn com o pip falha?

Porque sklearn é o nome de importação, não o nome do pacote. Existe um pacote fictício no PyPI cujo único objetivo é gerar um erro e redirecionar o utilizador — os seus mantenedores escolheram especificamente esse nome confuso para impedir que alguém mal-intencionado publicasse sob esse nome. Instale scikit-learn em vez disso.

Qual é a diferença entre o sklearn e o scikit-learn?

O scikit-learn é o nome do projeto e do pacote utilizado com o pip e o conda; o sklearn é o nome que se utiliza nas instruções import. Esta assimetria é permanente e é a razão pela qual o pacote de preenchimento existe.

Que versão do Python é necessária para o scikit-learn?

A versão 1.9.0, publicada em junho de 2026, requer o Python 3.11 ou posterior. As versões mais antigas do scikit-learn suportam versões mais antigas do Python, e o pip irá selecionar uma versão compatível em vez de falhar — o que, por vezes, explica porque é que uma funcionalidade sobre a qual leu está em falta.

Por que recebo um erro ModuleNotFoundError após a instalação?

Quase sempre se deve a um ambiente errado. Verifique import sys; print(sys.executable) e compare com o local onde instalou. No Jupyter, o ambiente do kernel é separado do do seu terminal — utilize %pip install scikit-learn dentro do notebook para instalar no kernel.

Devo usar o pip ou o conda?

O pip num ambiente virtual normal, que se adequa à maioria dos projetos e instala wheels pré-compilados em segundos. O conda se já estiver num ambiente conda ou se precisar de bibliotecas numéricas compiladas específicas. Evite misturá-los num único ambiente, uma vez que as perspetivas dos dois gestores de pacotes sobre o mesmo irão divergir.

Como posso verificar qual a versão do scikit-learn que tenho?

python -m pip show scikit-learn para ver a versão e a localização da instalação, ou python -c "import sklearn; sklearn.show_versions()" para obter um relatório completo, incluindo o Python e a pilha numérica — que é o que deve incluir ao reportar um problema.

Como instalo o scikit-learn através de um proxy?

Utilize pip install --proxy http://user:pass@host:port scikit-learn, ou defina http_proxy e https_proxy no seu ambiente para que o conda e outras ferramentas também os reconheçam. Codifique os caracteres especiais da palavra-passe com o símbolo de percentagem e configure o certificado CA da sua organização, em vez de desativar a verificação.

Conclusão

A instalação, por si só, resume-se a um único comando. Quase toda a dificuldade neste tópico decorre de dois aspetos que nada têm a ver com o próprio código do scikit-learn.

O primeiro é o nome. scikit-learn para instalar, sklearn para importar, e um pacote provisório com um nome que pode causar confusão, cuja função é interromper o utilizador e explicar o motivo. Esse pacote provisório é uma pequena medida de boa higiene na cadeia de abastecimento, e o erro que produz está a cumprir a sua função.

A segunda são os ambientes. Muitas falhas — o módulo que desaparece num novo terminal, o notebook que não consegue encontrar o que acabou de instalar, o erro de importação após uma atualização não relacionada — são, na verdade, um único problema de ambiente com diferentes manifestações. Um ambiente virtual por projeto, ativado deliberadamente, previne quase todos eles, e print(sys.executable) diagnostica o resto numa única linha.

E se pip ficar bloqueado em vez de apresentar um erro, verifica a tua rede antes de verificares o Python. Um proxy obrigatório que o pip não reconhece gera um timeout em vez de um erro, o que é uma forma confusa de aprenderes sobre a tua própria infraestrutura.