Modal Release Notes

• We’ve added a new modal app rollover CLI command for triggering a redeployment of an App without making any code or configuration changes. A rollover replaces existing containers with fresh ones. As with modal deploy, there are two strategies for switching between deployments:
• --strategy=rolling (the default) will smoothly migrate traffic from old containers to new containers
• --strategy=recreate will terminate all running containers so that any subsequent inputs will go to new containers
• We’ve added a new modal bootstrap CLI command, which fetches deployable starter code for common AI applications (e.g., text generation, text-to-image, speech-to-text). This is an experiment: try it out and give us feedback!
• We’ve added two methods to the new Sandbox filesystem API:
• sandbox.filesystem.make_directory() creates a new directory on the Sandbox filesystem
• sandbox.filesystem.remove() deletes a file or directory from the Sandbox filesystem
• The new Sandbox filesystem methods replace the modal.Sandbox.mkdir and modal.Sandbox.rm methods, which are now deprecated.
• The modal app stop and modal container stop CLI commands now prompt for confirmation (pass --yes to skip).
• Several other modal app CLI commands will now map a name-based argument to a recently-stopped App that used that name. This is useful for, e.g., fetching logs from an App after it has been stopped.
• We’ve added a build_args parameter to modal.Image.dockerfile_commands().

Release notes

• Sandboxes now support sb.unmount_image(path) to remove a previously mounted Image from a path and reveal the underlying Sandbox filesystem there again.

• We’re introducing a concept of “readiness probes” for modal.Sandbox. This feature lets you configure a readiness check on a TCP port (modal.Probe.with_tcp()) or by executing a process (modal.Probe.with_exec()). Calling sb.wait_until_ready() will block until the Probe succeeds:

app = modal.App.lookup(
    'sandbox-app'
    ,
    create_if_missing
    =
    True
)
probe = modal.Probe.with_tcp(
    8080
)
sb = modal.Sandbox.create(
    "python3"
    ,
    "-m"
    ,
    "http.server"
    ,
    "8080"
    ,
    readiness_probe
    =probe,
    app
    =
    app,
)
sb.wait_until_ready()

• We fixed a longstanding bug that could cause WebSocket performance to degrade after handling hundreds of connections from the same container.

• We improved the performance of modal container logs when fetching logs for an old container.

• We fixed a bug introduced in 1.4.0 that made the modal CLI crash on typer<0.19.0.

We’ve made significant CLI enhancements so that Modal logs can be more accessible to coding agents:

• The modal app logs and modal container logs commands now have the ability to fetch historical logs using counting (e.g. --tail 1000 ) or time-based (e.g., --since 4h , --until 2026-03-15 , etc.) configuration. Note that historical log access is subject to plan-level retention limits.
• The modal container logs command also accepts --all to fetch the complete set of logs for that Container or Sandbox.
• Both CLI commands now accept a --search filter, and they can also filter by --source ( stdout / stderr / system ).
• The modal app logs command additionally accepts --function , --function-call , and --container filters.
• The modal app logs command can prefix each line with the ID of the Function, FunctionCall, or Container where it originated (e.g. --show-function-id ).
• Note that the default behavior of these commands has changed. Previously, they would follow (i.e., stream) logs by default, but you now must pass --follow to get this behavior. The new default will always show the most recent 100 log entries.

We’re releasing a new Sandbox filesystem API (currently in Beta) with significantly improved reliability and ergonomics:

• Use sb.filesystem.copy_from_local / sb.filesystem.copy_to_local to transfer file contents between your local filesystem and the Sandbox filesystem.
• Use sb.filesystem.write_text / sb.filesystem.read_text or sb.filesystem.write_bytes / sb.filesystem.read_bytes to transfer file contents between local memory and the Sandbox filesystem.
• These new APIs replace the modal.Sandbox.open method and the modal.file_io.FileIO type that it returns; the old APIs are now deprecated.

We’re introducing the concept of “deployment strategies” to give you more flexibility over what happens when redeploying your App:

• By passing modal deploy --strategy recreate (or app.deploy(strategy="recreate") in the SDK), you can immediately terminate any containers that are running when the deployment completes. This is most useful for development workflows, as it guarantees that any subsequent input will be handled by containers running the new version of the App. This trades off some downtime for certainty about when the new version will be in use.
• The disruptive “recreate” strategy is also useful when your App runs at its max_containers limit, as otherwise we are unable to bring up replacement capacity.
• The modal serve command now uses a “recreate” strategy during code updates.
• The default “rolling” strategy is unchanged. This strategy prioritizes uptime, but means that old containers may still continue handling inputs for some time.

We’ve also included a number of smaller new features and improvements:

• Sandboxes now accept an include_oidc_identity_token parameter in modal.Sandbox.create. When set to True , a MODAL_IDENTITY_TOKEN environment variable will be injected into the Sandbox, enabling OIDC-based authentication (e.g., for AWS federation). See the OIDC integration guide for more details.
• The new modal.Image.from_scratch() constructor creates an empty Image, equivalent to FROM scratch in Docker. This is primarily useful as a lightweight filesystem to mount into a Sandbox via modal.Sandbox.mount_image.
• The modal container list command now accepts an --app-id filter to return containers for a specific App.
• We’ve addressed an issue where modal.Sandbox.exec could hang if the Sandbox had terminated immediately after creation.
• An exception is now raised if the same Volume or CloudBucketMount is mounted at multiple paths in a container.
• The client will now error faster (≈60s) if it cannot establish an initial connection the Modal servers.

Finally, we are introducing a small number of breaking changes and enforcing some deprecations of pre-1.0 APIs:

• Exceptions returned by modal.Function.map() are no longer wrapped in a UserCodeException type, and we’re deprecating the transitional wrap_returned_exceptions= parameter.
• The modal.enable_output() context manager no longer yields a value; this had briefly leaked an internal type.
• We’ve removed unused namespace parameters from a number of APIs.
• It’s now required to pass -m on the CLI when using a module path spelling of the Function reference (e.g. modal deploy -m project.app )
• We’ve removed backwards compatibility for the old autoscaler configuration ( keep_warm , concurrency_limit , etc.).
• It’s no longer possible to look up a specific method on a Cls using modal.Function.from_name ; use modal.Cls.from_name instead.

• 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.