Skip to content

feat!: Switch default HTTP client to httpx2 and use OS trust store by default - #3213

Merged
copybara-service[bot] merged 1 commit into
mainfrom
copybara/1006549935
Nov 4, 2026
Merged

copybara-service[bot] merged 1 commit into
mainfrom
copybara/1006549935

Conversation

@copybara-service

@copybara-service copybara-service Bot commented Oct 25, 2026 •

Copy link
Copy Markdown

feat!: Switch default HTTP client to httpx2 and use OS trust store by default

BREAKING CHANGE: httpx2 is now the required dependency and default HTTP client
instead of httpx, and default SSL verification with httpx2 uses the OS
certificate trust store (via truststore / httpx2.create_ssl_context()) when
SSL_CERT_FILE and SSL_CERT_DIR are not set. To maintain baseline behavior,
install google-genai[httpx] and set GOOGLE_GENAI_HTTP_CLIENT=httpx.

Summary of impact:

  • If your code uses httpx or httpx2 to interact with the SDK, make sure it
    uses the same package as the active SDK client.
  • In most cases, updating your code with import httpx2 as httpx is sufficient.
  • The SDK still fully supports both httpx and httpx2; only the default has
    changed.
  • httpx is no longer installed by default (use pip install google-genai[httpx]
    to install a compatible version; google-genai[httpx2] remains as a no-op
    extra).
  • You can set the SDK's default backend with GOOGLE_GENAI_HTTP_CLIENT (httpx
    or httpx2 strictly requires that package; unset or auto prefers httpx2
    and falls back to httpx if only httpx is installed).
  • Regardless of the default, passing HttpOptions(httpx_client=..., httpx_async_client=...)
    uses those objects directly (sync and async are configured independently).

Where httpx/httpx2 types must match the active client:

  • HttpOptions(client_args=..., async_client_args=...): package-specific objects
    such as Timeout, MockTransport / BaseTransport (and Response objects
    from mock handlers), and custom Auth subclasses must match the active client.
    Primitives (numeric timeouts, auth tuples, proxy URL strings) work with either.
  • Transport exceptions on client.models, files, etc.: network and timeout
    errors (TimeoutException, ConnectError, HTTPError) are reraised unwrapped
    after retries, so except clauses catching them directly must match the active
    client. (4xx/5xx APIError exceptions and client.interactions
    APIConnectionError / APITimeoutError are unchanged, though .response /
    .request attributes come from the active client.)

Fixes: #2680

@copybara-service copybara-service Bot changed the title No public description feat(client)!: Switch default HTTP client to httpx2 and use OS trust store by default Oct 27, 2026
@copybara-service
copybara-service Bot force-pushed the copybara/1006549935 branch 7 times, most recently from b357a5d to 5e2b9e6 Compare October 31, 2026 00:34
@copybara-service copybara-service Bot changed the title feat(client)!: Switch default HTTP client to httpx2 and use OS trust store by default fix!: Switch default HTTP client to httpx2 and use OS trust store by default Oct 31, 2026
@copybara-service
copybara-service Bot force-pushed the copybara/1006549935 branch 3 times, most recently from 73103e5 to cf858cf Compare November 3, 2026 06:52
@copybara-service copybara-service Bot changed the title fix!: Switch default HTTP client to httpx2 and use OS trust store by default feat!: Switch default HTTP client to httpx2 and use OS trust store by default Nov 3, 2026
… default

BREAKING CHANGE: `httpx2` is now the required dependency and default HTTP client
instead of `httpx`, and default SSL verification with `httpx2` uses the OS
certificate trust store (via `truststore` / `httpx2.create_ssl_context()`) when
`SSL_CERT_FILE` and `SSL_CERT_DIR` are not set. To maintain baseline behavior,
install `google-genai[httpx]` and set `GOOGLE_GENAI_HTTP_CLIENT=httpx`.

Summary of impact:
- If your code uses `httpx` or `httpx2` to interact with the SDK, make sure it
  uses the same package as the active SDK client.
- In most cases, updating your code with `import httpx2 as httpx` is sufficient.
- The SDK still fully supports both `httpx` and `httpx2`; only the default has
  changed.
- `httpx` is no longer installed by default (use `pip install google-genai[httpx]`
  to install a compatible version; `google-genai[httpx2]` remains as a no-op
  extra).
- You can set the SDK's default backend with `GOOGLE_GENAI_HTTP_CLIENT` (`httpx`
  or `httpx2` strictly requires that package; unset or `auto` prefers `httpx2`
  and falls back to `httpx` if only `httpx` is installed).
- Regardless of the default, passing `HttpOptions(httpx_client=..., httpx_async_client=...)`
  uses those objects directly (sync and async are configured independently).

Where `httpx`/`httpx2` types must match the active client:
- `HttpOptions(client_args=..., async_client_args=...)`: package-specific objects
  such as `Timeout`, `MockTransport` / `BaseTransport` (and `Response` objects
  from mock handlers), and custom `Auth` subclasses must match the active client.
  Primitives (numeric timeouts, auth tuples, proxy URL strings) work with either.
- Transport exceptions on `client.models`, `files`, etc.: network and timeout
  errors (`TimeoutException`, `ConnectError`, `HTTPError`) are reraised unwrapped
  after retries, so `except` clauses catching them directly must match the active
  client. (4xx/5xx `APIError` exceptions and `client.interactions`
  `APIConnectionError` / `APITimeoutError` are unchanged, though `.response` /
  `.request` attributes come from the active client.)

Fixes: #2680
PiperOrigin-RevId: 1013424989
@copybara-service
copybara-service Bot merged commit 51285c8 into main Nov 4, 2026
1 check passed
@copybara-service
copybara-service Bot deleted the copybara/1006549935 branch November 4, 2026 01:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Replace httpx with httpx2

1 participant