diff --git a/src/content/docs/environment.mdx b/src/content/docs/environment.mdx
index 96a5cbc4..a69fb37e 100644
--- a/src/content/docs/environment.mdx
+++ b/src/content/docs/environment.mdx
@@ -46,6 +46,11 @@ and production mode otherwise.
 `NODE_ENV` is a convention used in Node.js apps — the Python SDK reads
 `ARCJET_ENV` only.
 
+Python SDK users: if your config library doesn't propagate `.env` into
+`os.environ` (e.g. `pydantic-settings`), pass `ARCJET_ENV` via the
+`environment=` kwarg on `arcjet()` / `arcjet_sync()` — see the
+<Link.Page href="/reference/python#pydantic-settings-users">Python SDK reference</Link.Page>.
+
 In development, the timeout for connecting to Cloud API is increased.
 In production, the timeout is quicker.
 This is because in production your app typically runs close to an Arcjet server,
diff --git a/src/content/docs/reference/python.mdx b/src/content/docs/reference/python.mdx
index fadcb3c6..10603d43 100644
--- a/src/content/docs/reference/python.mdx
+++ b/src/content/docs/reference/python.mdx
@@ -129,6 +129,13 @@ The optional fields are:
   This is useful if you are behind a load balancer or proxy that sets the client
   IP address in a header. See [Load balancers &
   proxies](#load-balancers--proxies) below for an example.
+- `environment` (`str | None`) — Explicit development/production mode
+  (`"development"` or `"production"`). When `None` (default), falls back to
+  the
+  <Link.Page href="/environment#arcjet-env">`ARCJET_ENV`</Link.Page>
+  environment variable. Pass this when your config library doesn't propagate
+  `.env` into `os.environ` (e.g. `pydantic-settings`). See
+  [Pydantic-settings users](#pydantic-settings-users) below.
 
 <Tabs>
   <TabItem label="FastAPI (async)">
@@ -201,6 +208,41 @@ for more info.
 The `ARCJET_KEY` environment variable is not read automatically and must be
 passed explicitly via the `key` argument.
 
+#### Pydantic-settings users
+
+If you use
+[`pydantic-settings`](https://docs.pydantic.dev/latest/concepts/pydantic_settings/),
+pass
+<Link.Page href="/environment#arcjet-env">`ARCJET_ENV`</Link.Page>
+through the `environment=` kwarg. By design, pydantic-settings loads `.env`
+into a typed `BaseSettings` object rather than writing values back to
+`os.environ`, so the SDK — which reads `ARCJET_ENV` via `os.getenv` — won't
+pick up the value through that channel. Without the kwarg, the SDK defaults
+to production mode.
+
+```py
+from arcjet import arcjet
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env")
+
+    ARCJET_KEY: str
+    ARCJET_ENV: str = "development"
+
+
+settings = Settings()
+
+aj = arcjet(
+    key=settings.ARCJET_KEY,
+    rules=[...],
+    environment=settings.ARCJET_ENV,
+)
+```
+
+`arcjet_sync()` accepts the same kwarg.
+
 #### Load balancers & proxies
 
 If your application is behind a load balancer, Arcjet will only see the IP