localstack · giograno · Jul 17, 2025 · Jul 18, 2025
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -3,15 +3,15 @@
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
     # Ruff version.
-    rev: v0.12.3
+    rev: v0.12.4
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]
       # Run the formatter.
       - id: ruff-format
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.16.1
+    rev: v1.17.0
     hooks:
       - id: mypy
         entry: bash -c 'cd localstack-core && mypy --install-types --non-interactive'

@@ -1254,6 +1254,9 @@ def use_custom_dns():
 # This flag enables all responses from LocalStack to contain a `x-localstack` HTTP header.
 LOCALSTACK_RESPONSE_HEADER_ENABLED = is_env_not_false("LOCALSTACK_RESPONSE_HEADER_ENABLED")
 
+# Serialization backend for LocalStack state (stores and moto's backend dicts). Can be either `dill` or `json` (experimental)
+STATE_SERIALIZATION_BACKEND = os.environ.get("STATE_SERIALIZATION_BACKEND", "").strip() or "dill"
+
 # List of environment variable names used for configuration that are passed from the host into the LocalStack container.
 # => Synchronize this list with the above and the configuration docs:
 # https://docs.localstack.cloud/references/configuration/
@@ -1390,6 +1393,7 @@ def use_custom_dns():
     "SQS_ENDPOINT_STRATEGY",
     "SQS_DISABLE_CLOUDWATCH_METRICS",
     "SQS_CLOUDWATCH_METRICS_REPORT_INTERVAL",
+    "STATE_SERIALIZATION_BACKEND",
     "STRICT_SERVICE_LOADING",
     "TF_COMPAT_MODE",
     "USE_SSL",

diff --git a/localstack-core/localstack/state/json.py b/localstack-core/localstack/state/json.py
@@ -0,0 +1,68 @@
+from typing import IO, Any, Callable, Type, TypeVar
+
+import jsonpickle
+from jsonpickle.handlers import BaseHandler
+
+from localstack.state import Decoder, Encoder
+
+T = TypeVar("T", bound=BaseHandler)
+
+
+def jsonpickle_register(cls: Type = None) -> Callable[[Type[T]], Type[T]]:
+    """
+    Decorator to register a custom handler for jsonpickle serialization.
+    It provides a clean way to register custom jsonpickle handlers.
+
+    :param cls: the type to register the handler for
+    :raise ValueError: if the handler class does not extend handlers.BaseHandler
+    :return:
+
+    Example::
+
+        @jsonpickle_register(MyObject)
+        class MyObjectHandler(handlers.BaseHandler):
+            def flatten(self, obj: MyObject, data: dict) -> dict:
+                # ...
+                return data
+
+            def restore(self, data: dict) -> MyObject:
+                # ...
+                return MyObject(...)
+    """
+
+    def _wrapper(handler_class):
+        if not issubclass(handler_class, BaseHandler):
+            raise ValueError(f"Cannot register {handler_class}")
+
+        jsonpickle.handlers.register(cls, handler_class)
+        return handler_class
+
+    return _wrapper
+
+
+class JsonEncoder(Encoder):
+    """
+    An Encoder that uses ``jsonpickle`` under the hood.
+    """
+
+    def __init__(self, pickler_class: Type[jsonpickle.Pickler] = None):
+        self.pickler_class = pickler_class or jsonpickle.Pickler()
+
+    def encode(self, obj: Any, file: IO[bytes]):
+        json_str = jsonpickle.encode(obj, context=self.pickler_class)
+        file.write(json_str.encode("utf-8"))
+
+
+class JsonDecoder(Decoder):
+    """
+    A Decoder that uses ``jsonpickle`` under the hood.
+    """
+
+    unpickler_class: Type[jsonpickle.Unpickler]
+
+    def __init__(self, unpickler_class: Type[jsonpickle.Unpickler] = None):
+        self.unpickler_class = unpickler_class or jsonpickle.Unpickler()
+
+    def decode(self, file: IO[bytes]) -> Any:
+        json_str = file.read().decode("utf-8")
+        return jsonpickle.decode(json_str, context=self.unpickler_class)
diff --git a/localstack-core/localstack/state/pickle.py b/localstack-core/localstack/state/pickle.py
@@ -34,7 +34,10 @@ def _recreate(obj_type, obj_queue):
 import dill
 from dill._dill import MetaCatchingDict
 
+from localstack import config
+
 from .core import Decoder, Encoder
+from .json import JsonDecoder, JsonEncoder
 
 _T = TypeVar("_T")
 
@@ -134,44 +137,52 @@ def remove_dispatch_entry(cls: Type):
         pass
 
 
-def dumps(obj: Any) -> bytes:
+def dumps(obj: Any, encoder: Encoder | None = None) -> bytes:
     """
-    Pickle an object into bytes using a ``PickleEncoder``.
+    Pickle an object into bytes using an ``Encoder``.
 
     :param obj: the object to pickle
+    :param encoder: the encoder
     :return: the pickled object
     """
-    return PickleEncoder().encodes(obj)
+    encoder = encoder or _default_encoder
+    return encoder.encodes(obj)
 
 
-def dump(obj: Any, file: BinaryIO):
+def dump(obj: Any, file: BinaryIO, encoder: Encoder | None = None):
     """
-    Pickle an object into a buffer using a ``PickleEncoder``.
+    Pickle an object into a buffer using an ``Encoder``.
 
     :param obj: the object to pickle
+    :param encoder: the encoder
     :param file: the IO buffer
     """
-    return PickleEncoder().encode(obj, file)
+    encoder = encoder or _default_encoder
+    return encoder.encode(obj, file)
 
 
-def loads(data: bytes) -> Any:
+def loads(data: bytes, decoder: Decoder | None = None) -> Any:
     """
-    Unpickle am object from bytes using a ``PickleDecoder``.
+    Unpickle am object from bytes using a ``Decoder``.
 
     :param data: the pickled object
+    :param decoder: the decoder
     :return: the unpickled object
     """
-    return PickleDecoder().decodes(data)
+    decoder = decoder or _default_decoder
+    return decoder.decodes(data)
 
 
-def load(file: BinaryIO) -> Any:
+def load(file: BinaryIO, decoder: Decoder | None = None) -> Any:
     """
-    Unpickle am object from a buffer using a ``PickleDecoder``.
+    Unpickle am object from a buffer using a ``Decoder``.
 
     :param file: the buffer containing the pickled object
+    :param decoder: the decoder
     :return: the unpickled object
     """
-    return PickleDecoder().decode(file)
+    decoder = decoder or _default_decoder
+    return decoder.decode(file)
 
 
 class _SuperclassMatchingTypeDict(MetaCatchingDict):
@@ -255,6 +266,14 @@ def decode(self, file: BinaryIO) -> Any:
         return self.unpickler_class(file).load()
 
 
+_default_encoder = (
+    PickleEncoder() if config.STATE_SERIALIZATION_BACKEND == "dill" else JsonEncoder()
+)
+_default_decoder = (
+    PickleDecoder() if config.STATE_SERIALIZATION_BACKEND == "dill" else JsonDecoder()
+)
+
+
 class ObjectStateReducer(Generic[_T]):
     """
     A generalization of the following pattern::

@@ -30,6 +30,9 @@
     CrossRegionAttribute,
     LocalAttribute,
 )
+from localstack.state import pickle
+from localstack.state.json import JsonDecoder, JsonEncoder
+from localstack.state.pickle import PickleDecoder, PickleEncoder
 from localstack.testing.aws.cloudformation_utils import load_template_file, render_template
 from localstack.testing.aws.util import get_lambda_logs, is_aws_cloud
 from localstack.testing.config import (
@@ -2616,3 +2619,14 @@ def _delete_log_group():
             call_safe(_delete_log_group)
 
     yield _clean_up
+
+
+@pytest.fixture(
+    params=[(PickleEncoder(), PickleDecoder()), (JsonEncoder(), JsonDecoder())],
+    ids=["dill", "jsonpickle"],
+)
+def patch_default_encoder(request, monkeypatch):
+    encoder, decoder = request.param
+    monkeypatch.setattr(pickle, "_default_encoder", encoder)
+    monkeypatch.setattr(pickle, "_default_decoder", decoder)
+    return encoder, decoder
diff --git a/pyproject.toml b/pyproject.toml
@@ -61,6 +61,7 @@ base-runtime = [
     "dnspython>=1.16.0",
     "docker>=6.1.1",
     "jsonpatch>=1.24",
+    "jsonpickle==4.1.1",
     "hypercorn>=0.14.4",
     "localstack-twisted>=23.0",
     "openapi-core>=0.19.2",

diff --git a/requirements-base-runtime.txt b/requirements-base-runtime.txt
@@ -77,9 +77,11 @@ jmespath==1.0.1
     #   botocore
 jsonpatch==1.33
     # via localstack-core (pyproject.toml)
+jsonpickle==4.1.1
+    # via localstack-core (pyproject.toml)
 jsonpointer==3.0.0
     # via jsonpatch
-jsonschema==4.24.0
+jsonschema==4.24.1
     # via
     #   openapi-core
     #   openapi-schema-validator

diff --git a/requirements-dev.txt b/requirements-dev.txt
@@ -31,7 +31,7 @@ aws-cdk-asset-node-proxy-agent-v6==2.1.0
     # via aws-cdk-lib
 aws-cdk-cloud-assembly-schema==45.2.0
     # via aws-cdk-lib
-aws-cdk-lib==2.204.0
+aws-cdk-lib==2.206.0
     # via localstack-core
 aws-sam-translator==1.99.0
     # via
@@ -121,7 +121,7 @@ dill==0.3.6
     # via
     #   localstack-core
     #   localstack-core (pyproject.toml)
-distlib==0.3.9
+distlib==0.4.0
     # via virtualenv
 dnslib==0.9.26
     # via
@@ -215,9 +215,13 @@ jsonpath-ng==1.7.0
     #   moto-ext
 jsonpath-rw==1.4.0
     # via localstack-core
+jsonpickle==4.1.1
+    # via
+    #   aws-xray-sdk
+    #   localstack-core
 jsonpointer==3.0.0
     # via jsonpatch
-jsonschema==4.24.0
+jsonschema==4.24.1
     # via
     #   aws-sam-translator
     #   moto-ext
@@ -433,7 +437,7 @@ rsa==4.7.2
     # via awscli
 rstr==3.2.2
     # via localstack-core (pyproject.toml)
-ruff==0.12.3
+ruff==0.12.4
     # via localstack-core (pyproject.toml)
 s3transfer==0.13.0
     # via

diff --git a/requirements-runtime.txt b/requirements-runtime.txt
@@ -155,9 +155,11 @@ jsonpath-ng==1.7.0
     #   moto-ext
 jsonpath-rw==1.4.0
     # via localstack-core (pyproject.toml)
+jsonpickle==4.1.1
+    # via localstack-core
 jsonpointer==3.0.0
     # via jsonpatch
-jsonschema==4.24.0
+jsonschema==4.24.1
     # via
     #   aws-sam-translator
     #   moto-ext

diff --git a/requirements-test.txt b/requirements-test.txt
@@ -31,7 +31,7 @@ aws-cdk-asset-node-proxy-agent-v6==2.1.0
     # via aws-cdk-lib
 aws-cdk-cloud-assembly-schema==45.2.0
     # via aws-cdk-lib
-aws-cdk-lib==2.204.0
+aws-cdk-lib==2.206.0
     # via localstack-core (pyproject.toml)
 aws-sam-translator==1.99.0
     # via
@@ -199,9 +199,13 @@ jsonpath-ng==1.7.0
     #   moto-ext
 jsonpath-rw==1.4.0
     # via localstack-core
+jsonpickle==4.1.1
+    # via
+    #   aws-xray-sdk
+    #   localstack-core
 jsonpointer==3.0.0
     # via jsonpatch
-jsonschema==4.24.0
+jsonschema==4.24.1
     # via
     #   aws-sam-translator
     #   moto-ext