Como resolver erros de SSL ao instalar dependências com o pip em ambientes corporativos ?

Como resolver erros de SSL ao instalar dependências com o pip em ambientes corporativos ?

Visão Geral

Ambientes corporativos costumam ter políticas de segurança rígidas que restringem o acesso a determinados recursos da internet. Por isso, é comum que ocorram falhas ao utilizar ferramentas como o pip (gerenciador de pacotes do Python) em máquinas dentro da rede da empresa.

Um dos problemas mais frequentes é a falha na verificação do certificado SSL ao tentar instalar dependências, seja durante a execução do Runner ou em instalações manuais.

Sintoma Comum

Um erro típico que pode aparecer nos logs ou no terminal é semelhante ao exemplo abaixo:

WarningWARNING: Retrying (Retry(total=0, connect=None, read=None, redirect=None, status=None)) 
after connection broken by 'SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] 
certificate verify failed: unable to get local issuer certificate (_ssl.c:1000)'))': /simple/pip/

Could not fetch URL https://pypi.org/simple/pip/: There was a problem confirming the SSL certificate: HTTPSConnectionPool(host='pypi.org', port=443): 
Max retries exceeded with url: /simple/pip/ (Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] 
certificate verify failed: unable to get local issuer certificate (_ssl.c:1000)'))) - skipping

Esse erro indica que o Python não conseguiu validar o certificado SSL do repositório oficial de pacotes, o PyPI (Python Package Index).

Causa Provável

Esse tipo de falha normalmente acontece porque a rede da empresa bloqueia ou inspeciona conexões HTTPS, o que interfere na validação dos certificados SSL utilizados pelo pip.

1 – SSL Certificate Verification Error

  • Proxy corporativo que faz man‑in‑the‑middle TLS.

  • Certificado interno não instalado no trust‑store do sistema/Python.

2 – ConnectTimeoutError

  • Porta 443 bloqueada por firewall.

  • Endereço/DNS errado (ex.: https://developers.botcity.dev/).

  • Proxy obrigatório não configurado. [Como configurar o Proxy]

  • Servidor Maestro fora do ar.

Solução Proposta

Para contornar esse problema, é possível configurar o pip para confiar explicitamente nos domínios utilizados pelo PyPI.

Comando para configurar o pip com trusted-host:

pip config set global.trusted-host \
    "pypi.org files.pythonhosted.org pypi.python.org" \
    --trusted-host=pypi.python.org \
    --trusted-host=pypi.org \
    --trusted-host=files.pythonhosted.org

Essa configuração define uma lista de hosts confiáveis para o pip, permitindo que ele ignore erros de verificação SSL nesses domínios.

Importante

  • Essa é uma solução paliativa, recomendada somente em ambientes controlados.

  • Sempre valide com o time de TI da sua empresa se essa configuração é permitida conforme as políticas internas de segurança.

  • O time de TI também pode indicar configurações adicionais de proxy, certificados ou mirror interno para o uso do pip.


O bot falhou porque, dentro do Python, a chamada ao Maestro não ignorou o certificado autoassinado do proxy/servidor.
Ajuste a verificação SSL (desativar ou instalar o CA) antes de rodar novamente.
  1. from botcity.maestro import BotMaestroSDK

  3. maestro = BotMaestroSDK.from_sys_args()
  4. maestro.VERIFY_SSL_CERT = False  # Ignora a validação do certificado

Solução Expressa

No código do robô, defina a flag do Maestro SDK para ignorar o certificado SSL:

maestro.VERIFY_SSL_CERT = False

Assim o robô voltará a se conectar mesmo em ambientes que utilizam certificados autoassinados.

Saiba Mais

Para mais informações sobre bloqueios em ambientes corporativos, acesse a seção de Pré-requisitos da documentação oficial da BotCity.

Conclusão

Erros relacionados ao certificado SSL ao usar o pip são comuns em redes corporativas com restrições de segurança. Configurar os domínios do PyPI como trusted-host pode resolver temporariamente o problema, mas é essencial envolver o time de TI para garantir que a solução seja segura e definitiva.