@@ -727,7 +727,7 @@ Special handling for Colab:
727727- `prevent_initial_callbacks` - Skip callbacks on load (default: `False ` )
728728- `background_callback_manager` - DiskcacheManager or CeleryManager
729729- `on_error` - Global callback error handler
730- - `shared_storage` - Cross- process state + pub/ sub backend (default: `LocalSharedStorage` ). Pass `None ` to disable , or a `BaseSharedStorage` subclass/ instance to swap. See [Shared Storage](# shared-storage).
730+ - `shared_storage` - Cross- process state + pub/ sub backend (default: off ). Pass `LocalSharedStorage ` to enable , or a `BaseSharedStorage` subclass/ instance to swap. See [Shared Storage](# shared-storage).
731731
732732** WebSocket Callbacks:**
733733- `websocket_callbacks` - Enable WebSocket for all callbacks (default: `False ` ). Requires FastAPI backend.
@@ -820,7 +820,9 @@ channel. Unlike `dcc.Store` (which lives in the browser), shared storage lives
820820on the server and lets callbacks running in different workers see the same keys
821821and topics without standing up an external service like Redis.
822822
823- Enabled by default on every app. It starts lazily on first use, so it costs
823+ Opt- in : off unless the app passes `shared_storage=` or `DASH_SHARED_STORAGE `
824+ is set , so existing deployments do not grow a socket owner or a streaming
825+ downlink on upgrade. Once enabled it starts lazily on first use, so it costs
824826nothing until touched.
825827
826828# ## Accessing It
@@ -836,13 +838,21 @@ def handler(n):
836838 return store.get(" clicks" , 0 )
837839
838840# Or off the app directly:
839- app = dash.Dash()
841+ app = dash.Dash(shared_storage = dash.LocalSharedStorage )
840842app.shared_storage.set(" key" , {" any" : " json-compatible value" })
841843```
842844
843845Values (and published messages) must be ** JSON - compatible** — dict / list / str
844846/ int / float / bool / None — the same constraint as `dcc.Store` and callback
845- outputs. Messages are encoded with `msgspec` (msgpack), a hard dependency.
847+ outputs. Messages are encoded with `msgspec` (msgpack) from the
848+ `dash[shared_storage]` extra (also pulled in by `dash[diskcache]` and
849+ `dash[redis]` ). Without it, `LocalSharedStorage` in `" memory" ` mode still works
850+ and its socket transport falls back to stdlib JSON (both ends run the same
851+ install, so they always agree). JSON turns non- string dict keys into strings and
852+ cannot carry `bytes ` , so keep values strictly JSON - shaped. Everything that
853+ writes encoded bytes somewhere lasting (the persistent modes, Diskcache, Redis)
854+ raises an `ImportError ` naming the extra that brings it instead, so a stored
855+ format never depends on what happens to be installed.
846856
847857# ## API
848858
@@ -895,7 +905,7 @@ more than one container/pod (see [Deployment Topology](#deployment-topology-and-
895905
896906| Backend | Backing store | Reaches | Extra |
897907| -------- - | -------------- - | -------- - | ------ - |
898- | `LocalSharedStorage` * (default) * | in - memory, owner- elected socket | one ** container** (all its workers) | none |
908+ | `LocalSharedStorage` | in - memory, owner- elected socket | one ** container** (all its workers) | none ( `dash[shared_storage]` for the persistent modes) |
899909| `DiskcacheSharedStorage` | a `diskcache.Cache` | one ** host** (all processes sharing the dir ) | `dash[diskcache]` |
900910| `RedisSharedStorage` | Redis (Streams for pub/ sub) | ** any ** process/ container/ pod | `dash[redis]` |
901911
@@ -909,14 +919,21 @@ from dash._shared_storage import (
909919 LocalSharedStorage, DiskcacheSharedStorage, RedisSharedStorage,
910920)
911921
912- Dash(shared_storage = LocalSharedStorage) # default
922+ Dash() # disabled (default)
923+ Dash(shared_storage = LocalSharedStorage)
913924Dash(shared_storage = DiskcacheSharedStorage(directory = " /tmp/ss" ))
914925Dash(shared_storage = RedisSharedStorage(url = " redis://host:6379" ))
915- Dash(shared_storage = None ) # disabled
916926```
917927
918928When disabled, accessing `app.shared_storage` / `dash.ctx.shared_storage`
919- raises `SharedStorageError` .
929+ raises `SharedStorageError` . Streaming callbacks over HTTP need it: server setup
930+ raises `StreamCallbackError` naming them (`_validate.validate_stream_callbacks` ),
931+ so an app cannot stream on a fallback locally and then break once deployed.
932+ WebSocket streaming callbacks (`websocket_callbacks=True ` or `websocket=True `
933+ on a backend with `websocket_capability` , i.e. FastAPI or Quart) send frames on
934+ the socket and do not need it; on Flask those flags change nothing and the check
935+ still applies. Browsers without `SharedWorker` do not use the WebSocket
936+ transport and stream over HTTP , one connection per stream.
920937
921938** `LocalSharedStorage` ** — in - memory, no external service. On first use every
922939worker races to become the single ** owner** for the machine by binding a stable
@@ -993,7 +1010,7 @@ subscriptions likewise poll without blocking and sleep on the loop.
9931010
9941011# ## Deployment Topology and Shared Storage
9951012
996- The default `LocalSharedStorage` is ** per- container** : its socket/ loopback
1013+ `LocalSharedStorage` is ** per- container** : its socket/ loopback
9971014election only reaches processes in the same network + filesystem namespace.
9981015
9991016- ** Single process / single pod** (e.g. Plotly Cloud apps): fine — one owner,
@@ -1009,16 +1026,16 @@ election only reaches processes in the same network + filesystem namespace.
10091026A hosting platform can switch the backend without editing the app through
10101027`DASH_SHARED_STORAGE ` (`_shared_storage/ _env.py` ), read only when the app did
10111028not pass `shared_storage=` (the default is a sentinel, so an explicit argument,
1012- `None ` included, always wins): `local` , `none` , `diskcache: /// abs / path` , or a
1013- `redis:// ` / `rediss:// ` URL . A `key_prefix` query parameter on the Redis URL
1014- (`redis:// host/ 0 ? key_prefix=myapp` ) sets `RedisSharedStorage( key_prefix = )` and
1015- is stripped before the URL reaches redis - py; the diskcache path is
1016- percent- decoded. `cluster:// ` is reserved and raises; anything else raises
1017- `InvalidConfig` at construction, without echoing the value (it can hold
1018- credentials). The value becomes a zero- argument
1019- factory, so nothing is built or connected until `app.shared_storage` is first
1020- read, but a missing extra (`dash[redis]` , `dash[diskcache]` ) fails at
1021- construction with the backend' s own `ImportError`.
1029+ `None ` included, always wins): `local` , `none` (same as unset or empty),
1030+ `diskcache: /// abs / path` , or a ` redis:// ` / `rediss:// ` URL . A `key_prefix` query
1031+ parameter on the Redis URL (`redis:// host/ 0 ? key_prefix=myapp` ) sets
1032+ `RedisSharedStorage( key_prefix = )` and is stripped before the URL reaches
1033+ redis - py; the diskcache path is percent- decoded. `cluster:// ` is reserved and
1034+ raises; anything else raises `InvalidConfig` at construction, without echoing
1035+ the value (it can hold credentials). The value becomes a zero- argument factory,
1036+ so nothing is built or connected until `app.shared_storage` is first read, but a
1037+ missing extra (`dash[redis]` , `dash[diskcache]` , `dash[shared_storage]` ) fails
1038+ at construction with the backend' s own `ImportError`.
10221039
10231040# ## Custom and Out-of-Tree Backends
10241041
@@ -1039,12 +1056,13 @@ and returns a `Subscription` (`__iter__` / `__aiter__` / `close`) that raises
10391056top- level `dash` ; the poll- loop helpers (`PollResult` , the polling subscription)
10401057are private and not part of the contract.
10411058
1042- Core only ships backends whose dependency is already a Dash extra (`msgspec`
1043- base; `dash[diskcache]` ; `dash[redis]` ). Anything needing a heavier dependency
1044- belongs ** out of tree** behind this same interface — e.g. a Postgres backend
1045- (`LISTEN ` / `NOTIFY ` for push pub/ sub + a table for KV and replay) lives in its own
1046- package so a `psycopg` connection is never pulled into Dash core. It plugs in the
1047- same way as a built- in : `Dash(shared_storage = PostgresSharedStorage(... ))` .
1059+ Core only ships backends whose dependency is already a Dash extra
1060+ (`dash[shared_storage]` ; `dash[diskcache]` ; `dash[redis]` ). Anything needing a
1061+ heavier dependency belongs ** out of tree** behind this same interface — e.g. a
1062+ Postgres backend (`LISTEN ` / `NOTIFY ` for push pub/ sub + a table for KV and
1063+ replay) lives in its own package so a `psycopg` connection is never pulled into
1064+ Dash core. It plugs in the same way as a built- in :
1065+ `Dash(shared_storage = PostgresSharedStorage(... ))` .
10481066
10491067# ## Module Layout
10501068
@@ -1412,7 +1430,7 @@ with an empty result on the terminal frame.
14121430
14131431# ## Multiplexed downlink and the stream SharedWorker
14141432
1415- When the app has a shared- storage backend (the default `LocalSharedStorage` ),
1433+ When the app has a shared- storage backend (opt - in , see Shared Storage ),
14161434HTTP streams do not each hold their own response. The callback' s POST carries
14171435`streamConnection: {requestId}` and returns a fast ack; a * pump*
14181436(`dash/ _stream_hub.py` ) drives the generator as an asyncio task and publishes
0 commit comments