Python SSL Verify Failed: Fix the Chain Fast

You run a Python script that fetches one HTTPS URL and get slapped with ssl.SSLCertVerificationError: CERTIFICATE_VERIFY_FAILED. The site opens in your browser. Your coworker's laptop runs the same script fine. The traceback points at the ssl module and offers nothing else — no hint which certificate failed, which store was checked, or what to do next.

The gap is that Python doesn't share your browser's trust. Depending on the installer, your interpreter reads its own private CA bundle, the system OpenSSL paths, or whatever SSL_CERT_FILE points at — and on macOS it ignores the Keychain entirely. One missing root, one expired leaf, or one forgotten intermediate breaks the chain the same loud way.

This guide makes the failure boring. You'll learn how trust chains resolve in the ssl module, how to run the macOS certificate installer properly, where certifi and SSL_CERT_FILE fit, how corporate proxies and dev self-signed certs slot in, and why _create_unverified_context must never ship. By the end you'll clear any verify failure with evidence instead of incantations.

How Trust Chains Resolve in Python's ssl Module

A trust chain is a short ladder: the server's leaf certificate at the bottom, zero or more intermediates in the middle, and a root you already trust at the top. Python's ssl module climbs it with three inputs — the chain the server sent, the current time, and your CA bundle — checking each signature, each date window, and finally the hostname. CERTIFICATE_VERIFY_FAILED means one rung broke: a signature with no trusted anchor, dates outside today, a missing middle rung, or a name that doesn't match.

The context object holds your half of the bargain. ssl.create_default_context builds one with CERT_REQUIRED, hostname checking on, and the system bundle loaded — the safe baseline every connection should start from. The snippet prints exactly what that baseline resolves to on your machine: OpenSSL version, bundle paths, and the flags proving verification is active. Run it wherever a failure puzzles you before changing anything.

Keep one more fact handy: verification happens after the handshake bytes flow, so network tools will show a live connection right up to the refusal. Colleagues will say 'but I can reach the host' and they'll be right — reachability was never the question. Trust was. Once you separate those layers, the error stops feeling contradictory and starts reading as precise.

import os
import ssl

print("openssl version:", ssl.OPENSSL_VERSION)
print("default paths:", ssl.get_default_verify_paths())
print("SSL_CERT_FILE =", os.environ.get("SSL_CERT_FILE", "(not set)"))
ctx = ssl.create_default_context()
print("protocol:", ctx.protocol)
print("verify_mode:", ctx.verify_mode)
print("check_hostname:", ctx.check_hostname)
assert ctx.verify_mode == ssl.CERT_REQUIRED
assert ctx.check_hostname is True
print("default context verifies against the bundle")

macOS Install Certificates and the Keychain Gap

macOS python.org installers are the special case everyone trips over. They vendor their own OpenSSL and their own CA bundle under /Library/Frameworks, deliberately isolated from system updates — which also isolates them from the Keychain. When IT pushes a new root to managed Macs, Safari and curl pick it up; your python.org interpreter keeps reading yesterday's private bundle and failing.

The symptom pattern is unmistakable once you've seen it: Keychain shows green, Safari loads, brew Python passes, python.org Python fails — all on one machine. The snippet checks both halves: whether the installer command exists to refresh the bundle, and whether the resolved cafile is a live file with real certificates in it. A missing cafile or a zero-length bundle answers the mystery instantly.

The fix is refresh, not surgery. Run Install Certificates.command for your exact version — it downloads a current Mozilla bundle via certifi into the private path. For fleets, skip per-laptop rituals and export SSL_CERT_FILE to a managed bundle so python.org, brew, and venv interpreters all resolve identically. Either way, close the loop by re-running the failing call in the failing interpreter; the browser's green lock was never evidence about Python.

import pathlib
import ssl

candidates = [
    "/Applications/Python 3.14/Install Certificates.command",
    "/etc/ssl/cert.pem",
]
for c in candidates:
    print(c, "->", "present" if pathlib.Path(c).exists() else "absent")
paths = ssl.get_default_verify_paths()
print("cafile:", paths.cafile)
print("capath:", paths.capath)
if paths.cafile and pathlib.Path(paths.cafile).exists():
    data = pathlib.Path(paths.cafile).read_bytes()
    print("bundle size (bytes):", len(data))
    assert b"BEGIN CERTIFICATE" in data
    print("bundle holds certificates")
else:
    print("no live cafile; set SSL_CERT_FILE to a valid bundle")

certifi, SSL_CERT_FILE, and Who Reads What

certifi and SSL_CERT_FILE answer the same question — which roots do I trust — for different audiences. certifi is a curated snapshot of Mozilla's roots shipped as a Python package: identical on every OS, refreshed with pip, and the default behind Requests. SSL_CERT_FILE is OpenSSL's override switch: point it at any PEM file and every stdlib ssl context built afterward trusts exactly those roots. One travels with your code, the other with your environment.

The snippet loads both and counts the certifi roots so you can see the scale of what updates when you pip install -U certifi. The practical rule: let Requests default to certifi, and use SSL_CERT_FILE to cover everything else — stdlib clients, database drivers, subprocess tools. When a private root enters the picture, append it to a copy of the bundle and export both variables at the process level, never by editing files inside site-packages.

Beware the classic trap of upgrading certifi to fix a private-root failure. A fresh public bundle contains zero private roots, so the upgrade changes nothing and burns an hour. If the failing chain ends at your company's proxy or an internal CA, the only update that matters is adding that root to the file your process actually reads.

import certifi
import ssl

print("certifi bundle:", certifi.where())
ctx = ssl.create_default_context(cafile=certifi.where())
print("context from certifi, verify_mode:", ctx.verify_mode)
combo = ssl.create_default_context()
print("system context, verify_mode:", combo.verify_mode)
print("certifi cert count:",
      open(certifi.where(), "rb").read().count(b"BEGIN CERTIFICATE"))
print("use certifi where the OS store is thin; SSL_CERT_FILE elsewhere")

MITM Roots and the Office-Only Failure

Managed networks intercept TLS by design: the proxy terminates your session, scans the plaintext, and re-signs everything with a corporate root your employer controls. Your browser trusts it because device management installed the root system-wide. Python fails because its bundle — certifi's or the private macOS one — never received that root. Same laptop, same URL, different verdicts, all explained by which book of roots each program opened.

Diagnosis is environmental. The snippet dumps proxy variables alongside the client posture so you can see both halves in one screen: interception active, verification on. Confirm the pattern by switching networks — VPN or office Wi-Fi fails, phone hotspot passes — and by reading the issuer in s_client output, which will name your company instead of a public CA.

The fix is one root, installed once per environment. Obtain the corporate CA (IT portal or exported from the OS store), append it to your bundle copy, and export SSL_CERT_FILE plus REQUESTS_CA_BUNDLE wherever code runs: shells, CI, containers. What you must not do is normalize the bypass — a proxy you can see is still an attacker-shaped hole if your code stops authenticating. Trust the root explicitly and verification keeps protecting you from everyone else.

import os
import ssl

print("HTTP_PROXY =", os.environ.get("HTTP_PROXY", os.environ.get("http_proxy", "(none)")))
print("HTTPS_PROXY =", os.environ.get("HTTPS_PROXY", os.environ.get("https_proxy", "(none)")))
ctx = ssl.create_default_context()
print("client uses:", ctx.verify_mode, "hostname check:", ctx.check_hostname)
print("a MITM proxy re-signs with a corporate root;")
print("trust it by loading that root, never by disabling checks")

Dev Self-Signed Certs Without Disabling Checks

Development with HTTPS needs certificates, and self-signed ones are the quick kind that teach bad habits. A self-signed cert has no chain at all — issuer equals subject — so verification correctly rejects it everywhere except the machine that was told to trust it. The lazy answer is disabling checks in dev config that later ships to prod. The professional answer is a local CA: one root you generate once, install into your stores, and issue endless dev certs from.

mkcert makes this painless: mkcert -install creates the local root, mkcert localhost mints a proper-chained dev cert, and your Python code verifies normally with zero bypasses. The chain is real, the hostname matches, and the only trust added is a root that exists solely on your machine. When the app deploys, the dev root stays home and production chains validate against public roots untouched.

Treat any dev-only bypass as a live grenade. If a self-signed cert must be trusted ad hoc, load it narrowly with context.load_verify_locations into one context for one host — never a global unverified context, never CERT_NONE, never an env flag that production might inherit. Code review should reject verification bypasses the way it rejects hardcoded passwords: automatically, every time.

_create_unverified_context Is NOT a Fix

The last lesson is about the function you must never call. ssl._create_unverified_context builds a context with CERT_NONE and hostname checks disabled, and its leading underscore marks it private for a reason — it exists for exotic tooling, not applications. Yet it tops every search result for this error, complete with copy-paste instructions, which is how it ends up in production behind a comment saying temporary.

Compare it against the drill snippet: raising SSLCertVerificationError deliberately shows the structured fields — verify_code and verify_message — that let you branch on stable numbers instead of English prose. Code 10 expired, 18 self-signed, 20/21 chain gaps: those numbers survive OpenSSL upgrades while message wording drifts. Build handlers on codes and your automation keeps working after interpreter bumps.

Run the snippet, watch it raise the advertised error, and practice the correct response: catch the narrow type, log the code, apply the matching trust fix. Then grep your repos for the unverified constructor and CERT_NONE, and delete every hit with prejudice. A codebase with zero bypasses can't regress into silent insecurity — which is the entire point of verification in the first place.

import shutil
import socket
import ssl
import subprocess
import tempfile
import threading
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer


class H(BaseHTTPRequestHandler):
    def do_GET(self):
        body = b"ok"
        self.send_response(200)
        self.send_header("Content-Length", "2")
        self.end_headers()
        self.wfile.write(body)

    def log_message(self, *a):
        pass


tmp = tempfile.mkdtemp()
key, crt = tmp + "/k.pem", tmp + "/c.pem"
subprocess.run(
    [shutil.which("openssl"), "req", "-x509", "-newkey", "rsa:2048",
     "-keyout", key, "-out", crt, "-days", "1", "-nodes",
     "-subj", "/CN=127.0.0.1"],
    check=True, capture_output=True,
)
srv = ThreadingHTTPServer(("127.0.0.1", 0), H)
srv_ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
srv_ctx.load_cert_chain(crt, key)
srv.socket = srv_ctx.wrap_socket(srv.socket, server_side=True)
port = srv.server_address[1]
threading.Thread(target=srv.serve_forever, daemon=True).start()
try:
    raw = socket.create_connection(("127.0.0.1", port), timeout=10)
    ctx = ssl.create_default_context()
    tls = ctx.wrap_socket(raw, server_hostname="127.0.0.1")
    tls.close()
    print("UNEXPECTED: self-signed cert verified")
except ssl.SSLCertVerificationError as e:
    print("caught advertised error:", type(e).__name__)
    print("verify_code:", e.verify_code, "message:", e.verify_message)
    assert e.verify_code == 18
    raise
finally:
    srv.shutdown()
    srv.server_close()