Error guide
Fix yt-dlp SSL errors: CERTIFICATE_VERIFY_FAILED and UNEXPECTED_EOF
yt-dlp's SSL errors all look alike, but the part after certificate verify failed:tells you whose problem it is. Most of the time it's your network, not the site, and the fix is to make yt-dlp trust the same certificates your browser does. Turning verification off works too, but it should be the last thing you try.
Quick answer
# 1. update first
yt-dlp -U
# 2. behind a company proxy, VPN or antivirus: use the system certificate store
yt-dlp --compat-options no-certifi "<URL>"
# 3. last resort, one-off only: skip verification
yt-dlp --no-check-certificates "<URL>"Step 2 fixes the most common case, unable to get local issuer certificate. The sections below match each message to its cause.
Read the reason in the error
We triggered each variant on purpose with yt-dlp 2026.10.26 against the badssl.com test hosts (November 2026). The full message is long; this is the part that matters:
ERROR: [generic] expired.badssl: Unable to download webpage:
[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: certificate has expired (_ssl.c:1018)
... certificate verify failed: self-signed certificate (_ssl.c:1018)
... certificate verify failed: self-signed certificate in certificate chain (_ssl.c:1018)
... certificate verify failed: Hostname mismatch, certificate is not valid for 'wrong.host.badssl.com'.- unable to get local issuer certificate or self-signed certificate in certificate chain: yt-dlp doesn't trust the certificate that signed the connection. On a work network, VPN or with HTTPS-scanning antivirus, that's the inspecting proxy's own certificate. See the next section.
- certificate has expired: check your computer's date and time first (a wrong clock makes valid certificates look expired). If the clock is right, the site let its certificate lapse, and only the site can fix it.
- Hostname mismatch: the certificate is for a different domain. Check the URL (a mirror or an old domain), or something on your network is redirecting the connection.
- self-signed certificate: the server isn't using a public certificate at all, which is normal for a home server or a NAS. Skip verification for that host only.
Why your browser works and yt-dlp doesn't: certifi
yt-dlp picks its list of trusted certificates like this: if the Python package certifiis installed, it trusts certifi's bundle only. If not, it uses the operating system's store. Your browser uses the system store, and that's where IT installs the company proxy's certificate, so the browser is happy and yt-dlp isn't.
Check which one you have. The verbose header lists optional libraries:
yt-dlp -v --simulate "<URL>" 2>&1 | grep "Optional libraries"
[debug] Optional libraries: Cryptodome-3.24.2, brotli-1.2.1, certifi-2026.10.23, mutagen-1.48.1, ...If certifi is in that list, tell yt-dlp to use the system store instead:
yt-dlp --compat-options no-certifi "<URL>"
# or make it permanent in your config file (~/.config/yt-dlp/config on Linux/macOS)
--compat-options no-certifiIn our test, pip install "yt-dlp[default]" brought certifi in and a bare pip install yt-dlpdidn't; without it the system store is used already. In that case, if the proxy's certificate isn't in the system store, point Python at a bundle that contains it with SSL_CERT_FILE=/path/to/company-ca.pem (ask IT for the file). On macOS with Python from python.org, run the Install Certificates.command that came with it once.
UNEXPECTED_EOF_WHILE_READING
[SSL: UNEXPECTED_EOF_WHILE_READING] EOF occurred in violation of protocol (_ssl.c:1085)This one isn't about certificates. The connection was closed in the middle of the TLS exchange, by the server or by something in between. It was reported again this month (yt-dlp#18060). Work through it in this order:
- Update yt-dlp (
yt-dlp -U) and retry; one-off drops happen. - Turn off the VPN or proxy, or remove
--proxy, and try again. A proxy that can't handle the site's TLS is the usual cause. - Try
--force-ipv4. Broken IPv6 routes can show up as dropped connections. - If it only happens after many downloads in a row, the site is cutting you off. Slow down (see avoiding rate limits).
A related one is UNSAFE_LEGACY_RENEGOTIATION_DISABLED, from old servers that newer OpenSSL refuses to talk to. --legacy-server-connect allows it for that run.
The mistake to avoid
Don't put --no-check-certificates in your config file to make the error go away. It turns off verification for every site, including ones you send cookies to. Fix the trust list with --compat-options no-certifi or SSL_CERT_FILE, and keep --no-check-certificates for a single command against a host you know, like a self-signed home server.
If it keeps breaking
Tired of fixing this every time a site changes?
Paste a link to see what a managed import API returns — the one that stays current so your workflow doesn't break.
Building this into an app? See the API your backend calls instead
Frequently asked questions
How do I fix CERTIFICATE_VERIFY_FAILED in yt-dlp?
Read the reason after "certificate verify failed". "unable to get local issuer certificate" usually means a corporate proxy, VPN or antivirus is inspecting HTTPS: try --compat-options no-certifi so yt-dlp uses your system's certificate store, where that proxy's root certificate is installed. "certificate has expired" or "Hostname mismatch" is a problem on the site's side (or a wrong system clock). --no-check-certificates is the last resort, not the first fix.
Is --no-check-certificates safe?
It turns off the check that you're talking to the real site, so anything between you and the server can read or change the traffic. For a one-off public download it's a common workaround; don't put it in a script that also sends cookies or runs on a server you care about.
Why does yt-dlp fail with SSL errors when my browser opens the same page fine?
They can trust different certificate lists. Browsers use the operating system's store (where a company proxy's certificate gets installed), while yt-dlp uses the certifi bundle when certifi is installed. --compat-options no-certifi makes yt-dlp use the system store instead.
What does UNEXPECTED_EOF_WHILE_READING mean in yt-dlp?
The TLS connection was closed before the handshake or the response finished. It isn't a certificate problem. It usually comes from something in between (a proxy, VPN, firewall or antivirus) or from the server dropping you. Update yt-dlp, retry, and try without the proxy or VPN, or with --force-ipv4.