Add ssl_context_factory for custom SSLContext configuration

[Kludex]

• Closes Support custom SSL Context #806
• Supersedes Add ssl_context_factory parameter for custom SSL contexts #2833

Summary

Adds an ssl_context_factory parameter to Config and uvicorn.run() for advanced TLS scenarios that the existing ssl_* flags don't cover (mutual TLS, certificate pinning, custom SSLContext.options, password-protected keys loaded from memory, etc.).

The factory receives the Config and a default_ssl_context_factory callable that builds the standard context from the ssl_* settings. Users can either start from the default and mutate it, or build their own context from scratch.

The design is inspired by gunicorn's ssl_context hook.

Usage

from __future__ import annotations

import ssl
from collections.abc import Callable

import uvicorn
from uvicorn.config import Config


def ssl_context_factory(config: Config, default_ssl_context_factory: Callable[[], ssl.SSLContext]) -> ssl.SSLContext:
    context = default_ssl_context_factory()
    context.minimum_version = ssl.TLSVersion.TLSv1_3
    return context


uvicorn.run(
    "main:app",
    ssl_keyfile="key.pem",
    ssl_certfile="cert.pem",
    ssl_context_factory=ssl_context_factory,
)

Behaviour

• The factory is called inside Config.load(), which runs in each worker process, so it works with --reload and --workers > 1. The factory itself must be picklable in those modes (a top-level function works; a lambda or local closure does not).
• When ssl_context_factory is set together with ssl_keyfile / ssl_certfile, a warning is logged - those values are only used by the default factory the user receives, not directly by uvicorn.
• A TypeError is raised if the factory returns something other than an ssl.SSLContext.
• is_ssl returns True when the factory is set, even without ssl_keyfile / ssl_certfile.
• No CLI flag - this is a programmatic-only API.

Checklist

• I understand that this PR may be closed in case there was no previous discussion. (This doesn't apply to typos!)
• I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
• I've updated the documentation accordingly.

AI Disclaimer

This PR was developed with the assistance of either Claude or Codex. I've reviewed and verified the changes.

[github-actions]

📖 Docs preview: https://3a5dd082.uvicorn.pages.dev

[codspeed-hq]

Merging this PR will not alter performance

✅ 24 untouched benchmarks

---

_{Comparing ssl-context-factory (68b9975) with main (b499bc4)}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 185e0d4f02

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".