tooolbox/blog/Python pip install SSL Errors on Linux: Causes and Fixes
troubleshooting2024-10-25·11 min·257/348

Python pip install SSL Errors on Linux: Causes and Fixes

Resolving SSL certificate and connection errors when using pip on Linux, including corporate proxy issues, outdated certificates, and OpenSSL configuration.

Introduction

Few things are as frustrating as running pip install and being greeted by an SSL error that makes no sense. The certificate looks fine, your browser connects to PyPI without issues, yet pip refuses to work. SSL errors on Linux are usually caused by outdated CA certificates, corporate proxies intercepting HTTPS traffic, or Python being compiled against the wrong OpenSSL version. This post covers the most common causes and fixes.

Environment

The examples use Python 3.11 on Ubuntu 22.04 LTS with pip 23.3.1. The issues described also affect CentOS, Debian, and other distributions.

python3 --version
# Python 3.11.6

pip --version
# pip 23.3.1 from /usr/lib/python3/dist-packages/pip (python 3.11)

Problem

Running pip install results in SSL errors:

pip install requests
# ERROR: Could not install packages due to an EnvironmentError: SSLError
# Max retries exceeded with url: /simple/requests/
# (Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED]
# certificate verify failed: self-signed certificate in certificate chain')))

Or a different variation:

pip install numpy
# WARNING: pip is configured with locations that require TLS/SSL, however the ssl module in Python is not available.
# ERROR: Could not install packages due to an EnvironmentError: Missing dependencies for ssl!

Analysis

There are several distinct SSL error patterns:

1. Certificate verification failed (self-signed certificate)

This usually means a corporate proxy is intercepting HTTPS traffic:

# Check if a proxy is configured
env | grep -i proxy
# https_proxy=http://proxy.company.com:8080
# http_proxy=http://proxy.company.com:8080

2. ssl module not available

Python was compiled without SSL support:

python3 -c "import ssl; print(ssl.OPENSSL_VERSION)"
# If this fails, Python lacks SSL support

3. Certificate not found

The system CA certificates are missing or not in the expected location:

ls /etc/ssl/certs/ca-certificates.crt
# ls: cannot access '/etc/ssl/certs/ca-certificates.crt': No such file or directory

Solution

1. Install system CA certificates

# Debian/Ubuntu
sudo apt-get update
sudo apt-get install ca-certificates
sudo update-ca-certificates

# CentOS/RHEL
sudo yum install ca-certificates
sudo update-ca-trust force-enable

2. For corporate proxy environments

Option A: Install the corporate CA certificate:

# Download the corporate CA certificate
curl -o corporate-ca.crt https://proxy.company.com/ca.crt

# Add to system store
sudo cp corporate-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

# Or use the REQUESTS_CA_BUNDLE environment variable
export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt

Option B: Disable SSL verification (not recommended for production):

pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org requests

Option C: Configure pip to use the corporate proxy:

# ~/.pip/pip.conf
[global]
proxy = http://proxy.company.com:8080

# Or set environment variables
export https_proxy=http://proxy.company.com:8080
export http_proxy=http://proxy.company.com:8080

3. Fix Python SSL module issues

# Check if ssl module works
python3 -c "import ssl; print(ssl.OPENSSL_VERSION)"

# If missing, reinstall Python with SSL support
sudo apt-get install python3 python3-dev libssl-dev

# Rebuild Python if installed from source
cd Python-3.11.6
./configure --with-ssl
make
sudo make install

4. Update pip and certificates

# Upgrade pip
python3 -m pip install --upgrade pip

# Install certifi for certificate management
pip install certifi

# Set the certificate bundle
export SSL_CERT_FILE=$(python3 -c "import certifi; print(certifi.where())")

5. Use a virtual environment

python3 -m venv myenv
source myenv/bin/activate

# The virtual environment uses its own pip
pip install requests

6. Check OpenSSL version

openssl version
# OpenSSL 3.0.2 15 Mar 2022

python3 -c "import ssl; print(ssl.OPENSSL_VERSION)"
# OpenSSL 3.0.2 15 Mar 2022

If the versions do not match, Python was linked against a different OpenSSL.

7. Use pip with explicit certificate

pip install --cert /etc/ssl/certs/ca-certificates.crt requests

8. Configure pip globally

# ~/.pip/pip.conf (or %APPDATA%\pip\pip.ini on Windows)
[global]
trusted-host = pypi.org
               files.pythonhosted.org

[install]
trusted-host = pypi.org
               files.pythonhosted.org

9. Debug SSL issues

# Test SSL connection to PyPI
openssl s_client -connect pypi.org:443 -CAfile /etc/ssl/certs/ca-certificates.crt

# Check certificate chain
python3 -c "
import ssl
import urllib.request
context = ssl.create_default_context()
response = urllib.request.urlopen('https://pypi.org', context=context)
print('SSL connection successful')
"

10. Use alternative package indexes

# Use a mirror
pip install -i https://mirrors.aliyun.com/pypi/simple/ requests

# Use a local mirror
pip install --index-url http://localhost:8080/simple/ requests

Lessons Learned

SSL errors on Linux usually have simple causes: missing CA certificates, corporate proxy interception, or Python compiled without SSL support. Always start by checking openssl version and python3 -c "import ssl". For corporate environments, the cleanest solution is installing the corporate CA certificate system-wide. Avoid disabling SSL verification, as it opens you to man-in-the-middle attacks. And keep your system CA certificates updated regularly.

This blog does not accept any external sponsorships, affiliate marketing, or ad revenue.