Modal Release Notes

• We’ve added a modal changelog CLI for retrieving changelog entries with a flexible query interface (e.g. modal changelog --since=1.2 , modal changelog --since=2025-12-01 , modal changelog --newer ). We expect that this will be a useful way to surface information about new features to coding agents.

• We’ve added a new modal.Secret.update method, which allows you to programmatically modify the environment variables within a Secret. This method has the semantics of Python’s dict.update : Secret contents can be overwritten or extended when using it. Note that Secret updates will take effect only for containers that start up after the modification.

• The dataclass returned by modal.Function.get_current_stats() now includes a num_running_inputs field that reports the number of inputs the Function is currently handling.

• We’re introducing “Directory Snapshots”: a new beta feature for persisting specific directories past the lifetime of an individual Sandbox. Using the new methods modal.Sandbox.snapshot_directory() and modal.Sandbox.mount_image(), you can capture the state of a directory and then later include it in a different Sandbox:

sb = modal.Sandbox.create(app=app)
snapshot = sb.snapshot_directory("/project")
sb2 = modal.Sandbox.create(app=app)
sb2.mount_image("/project", snapshot)

This feature can be useful for separating the lifecycle of application code in the Sandbox’s main Image from project code that changes in each Sandbox session. Files in the mounted snapshot also benefit from several optimizations that allow them to be read faster. See the Sandbox Snapshot guide for more information.

• We’ve added a new modal.Sandbox.detach() method that we recommend calling after you are done interacting with a Sandbox. This method disconnects your local client from the Sandbox and cleans up resources associated with the connection. After calling detach, operations on the Sandbox object may raise and are otherwise not guaranteed to work.

• The modal.Sandbox.terminate() method now accepts a wait parameter. With wait=True, terminate will block until the Sandbox is finished and return the exit code. The default wait=False maintains the previous behavior.

• Throughput for writing to the stdin of a modal.Sandbox.exec process has been increased by 8x.

• We’ve added a new modal.Volume.from_id() method for referencing a Volume by its object id.

• We’ve added a new modal billing report CLI and promoted the modal.billing.workspace_billing_report API to General Availability for all Team and Enterprise plan workspaces.
• We’ve added modal.Queue.from_id() and modal.Dict.from_id() methods to support referencing a Queue or Dict by its object id.
• Modal’s async usage warnings are now enabled by default. These warnings will fire when using a blocking interface on a Modal object in an async context. We’ve aimed to provide detailed and actionable suggestions for how to modify the code, which makes the warnings verbose. While we recommend addressing any warnings that pop up, as they can point to significant performance issues or bugs, we also provide a configuration option to disable them (MODAL_ASYNC_WARNINGS=0 or async_warnings = false in the .modal.toml). Please report any apparent false positives or incorrect suggested fixes.
• We’ve fixed a bug where the ASGI scope’s state contents could leak between requests when using @modal.asgi_app.

• Modal objects now have a .get_dashboard_url() method. This method will return a URL for viewing that object on the Modal dashboard:

  fc = f.spawn()
  print(fc.get_dashboard_url())
  # Easy access to logs, etc.
  

• There is also a new modal dashboard CLI and new modal app dashboard / modal volume dashboard CLI subcommands:

  • modal dashboard # Opens up the Apps homepage for the current environment
  • modal dashboard <object-id> # Opens up a view of this object
  • modal app dashboard <app-name> # Opens up the dashboard for this deployed App
  • modal volume dashboard <volume-name> # Opens up the file browser for this persistent Volume

• You can now pass a Sandbox ID (sb-xxxxx) directly to the modal container logs CLI.

• The modal token info CLI will now include the token name, if provided at token creation.

• We’ve fixed an issue where modal.Cls.with_options() (or the with_concurrency() / with_batching() methods) could sometimes use stale argument values when called repeatedly.

• We’ve improved our experimental support for Python 3.14t (free-threaded Python) inside Modal containers.

  • The container environment will now use the Python implementation of the Protobuf runtime rather than the incompatible upb implementation.

  • As 3.14t images are not being published to the official source for our prebuilt modal.Image.debian_slim() images, we recommend using modal.Image.from_registry to build a 3.14t Image:

    modal.Image.from_registry(
      "debian:bookworm-slim",
      add_python="3.14t"
    )
    

• Note that 3.14t support is available only on the 2025.06 Image Builder Version.

• Support is still experimental, so please share any issues that you encounter running 3.14t in Modal containers.

• It’s now possible to provide a custom_domain for a modal.Sandbox:

  sb = modal.Sandbox.create(..., custom_domain="sandboxes.mydomain.com")
  

  Note that Sandbox custom domains work differently from Function custom domains and must currently be set up manually by Modal; please get in touch if this feature interests you.

• We added a new modal token info CLI command to retrieve information about the credentials that are currently in use.

• We added a --timestamps flag to a number of CLI entrypoints (modal run, modal serve, modal deploy, and modal container logs) to show timestamps in the logging output.

• The automatic CLI creation for modal run entrypoints now supports Literal type annotations, provided that the literal type contains either all str or all int values.

• We’ve fixed a bug that could cause App builds to fail with an uninformative CancelledError when the App was misconfigured.

• We’ve improved client resource management when running modal.Sandbox.exec, which avoids a rare thread race condition.

Modal now supports Python 3.14. Python 3.14t (the free-threading build) support is currently a work in progress, because we are waiting for dependencies to be updated with free-threaded support. Additionally, Modal no longer supports Python 3.9, which has reached end-of-life.

We are adding experimental support for detecting cases where Modal’s blocking APIs are used in async contexts (which can be a source of bugs or performance issues). You can opt into runtime warnings by setting MODAL_ASYNC_WARNINGS=1 as an environment variable or async_warnings = true as a config field. We will enable these warnings by default in the future; please report any apparent false positives or other issues while support is experimental.

This release also includes a small number of deprecations and behavioral changes:

• The Modal SDK will no longer propagate grpclib.GRPCError types out to the user; our own modal.Error subtypes will be used instead. To avoid disrupting user code that has relied on GRPCError exceptions for control flow, we are temporarily making some exception types inherit from GRPCError so that they will also be caught by except grpclib.GRPCError statements. Accessing the .status attribute of the exception will issue a deprecation warning, but warnings cannot be issued if the exception object is only caught and there is no other interaction with it. We advise proactively migrating any exception handling to use Modal types, as we will remove the dependency on grpclib types entirely in the future. See the modal.exception docs for the mapping from gRPC status codes to Modal exception types.

• The max_inputs parameter in the @app.function() and @app.cls decorators has been renamed to single_use_containers and now takes a boolean value rather than an integer. Note that only max_inputs=1 has been supported, so this has no functional implications. This change is being made to reduce confusion with @modal.concurrent(max_inputs=...) and so that Modal’s autoscaler can provide better performance for Functions with single-use containers.

• The async (.aio) interface has been deprecated from modal.FunctionCall.from_id, modal.Image.from_id, and modal.SandboxSnapshot.from_id, because these methods do not perform I/O.

• The replace_bytes and delete_bytes methods have been removed from the modal.file_io filesystem interface.

• Images built with modal.Image.micromamba() using the 2023.12 Image Builder Version will now use a Python version that matches their local environment by default, rather than defaulting to Python 3.9.

• It is now possible to set a custom name= for a Function without using serialized=True. This can be useful when decorating a function multiple times, e.g. applying multiple Modal configurations to the same implementation.
• It is now possible to start modal shell with a Modal Image ID (modal shell im-abc123). Additionally, modal shell will now warn if you pass invalid combinations of arguments (like --cpu together with the ID of an already running Sandbox, etc.).
• Fixed a bug in modal shell that caused e.g. vi to fail with unicode decode errors.
• Fixed a thread-safety issue in modal.Sandbox resource cleanup.
• Improved performance when adding large local directories to an Image.
• Improved async Sandbox performance by not blocking the event loop while reading from stdout or stderr.

• CPU Functions can now be configured to run on non-preemptible capacity by setting nonpreemptible=True in the @app.function() or @app.cls() decorator. This feature is not currently available when requesting a GPU. Note that non-preemptibility incurs a 3x multiplier on CPU and memory pricing. See the Guide for more information on preemptions.

• The Modal client can now respond more gracefully to server throttling (e.g., rate limiting) by backing off and automatically retrying. This behavior can be controlled with a new MODAL_MAX_THROTTLE_WAIT config variable. Setting the config to 0 will preserve the previous behavior and treat rate limits as an exception; setting it to a nonzero number (the unit is seconds) will allow a limited duration of retries.

• The modal.Sandbox.exec implementation has been rewritten to be more reliable and efficient.

• Added a new --add-local flag to modal shell, allowing local files and directories to be included in the shell’s container.

• Fixed a bug introduced in v1.2.2 where some Modal objects (e.g., modal.FunctionCall) were not usable after being captured in a Memory Snapshot. The bug would result in a has no loader function error when the object was used.