This changelog documents user-facing updates (features, enhancements, fixes, and deprecations) to the modal client library. Patch releases are made on every change.

The client library is still in pre-1.0 development, and sometimes breaking changes are necessary. We try to minimize them and publish deprecation warnings / migration guides in advance, typically providing a transition window of several months.

You can also refer to the 1.0 migration guide for a summary of major breaking changes that we are rolling out before releasing version 1.0.

We appreciate your patience while we speedily work towards a stable release of the client.

• Adds support for new strict bytes type for modal.parameter

Usage:

import typing
import modal

app = modal.App()


@app.cls()
class Foo:
    a: bytes = modal.parameter(default=b"hello")

    @modal.method()
    def bar(self):
        return f"hello {self.a}"


@app.local_entrypoint()
def main():
    foo = Foo(a=b"world")
    foo.bar.remote()

Note: For parameterized web endoints you must base64 encode the bytes before passing them in as a query parameter.

• Include git commit info at the time of app deployment.

• Added Image.cmd() for setting image default entrypoint args (a.k.a. CMD).

• Fixes a bug which could cause Function.map and sibling methods to stall indefinitely if there was an exception in the input iterator itself (i.e. not the mapper function)

• The @modal.web_endpoint decorator is now deprecated. We are replacing it with @modal.fastapi_endpoint. This can be a simple name substitution in your code; the two decorators have identical semantics.

• The keep_warm= parameter has been removed from the@modal.method decorator. This parameter has been nonfunctional since v0.63.0; all autoscaler configuration must be done at the level of the modal Cls.

• Adds modal.fastapi_endpoint as an alias for modal.web_endpoint. We will be deprecating the modal.web_endpoint name (but not the functionality) as part of the Modal 1.0 release.

• The wait_for_response parameter of Modal's web endpoint decorators has been removed (originally deprecated in May 2024).

• It is now possible to call Cls.with_options on an unhydrated Cls, e.g.

  ModelWithGPU = modal.Cls.from_name("my-app", "Model").with_options(gpu="H100")

• Cls.with_options() now accept unhydated volume and secrets

• We're renaming several App.function and App.cls parameters that configure the behavior of Modal's autoscaler:
  • concurrency_limit is now max_containers
  • keep_warm is now min_containers
  • container_idle_timeout is now scaledown_window
• The old names will continue to work, but using them will issue a deprecation warning. The aim of the renaming is to reduce some persistent confusion about what these parameters mean. Code updates should require only a simple substitution of the new name.
• We're adding a new parameter, buffer_containers (previously available as _experimental_buffer_containers). When your Function is actively handling inputs, the autoscaler will spin up additional buffer_containers so that subsequent inputs will not be blocked on cold starts. When the Function is idle, it will still scale down to the value given by min_containers.

• Adds a new config field, ignore_cache (also accessible via environment variables as MODAL_IGNORE_CACHE=1), which will force Images used by the App to rebuild but not clobber any existing cached Images. This can be useful for testing an App's robustness to Image rebuilds without affecting other Apps that depend on the same base Image layer(s).

• Adds a deprecation warning to the workspace parameter in modal.Cls lookup methods. This argument is unused and will be removed in the future.

• We've moved the modal.functions.gather function to be a staticmethod on modal.FunctionCall.gather. The former spelling has been deprecated and will be removed in a future version.

• Fixes issue where running modal shell with a dot-separated module reference as input would not accept the required -m flag for "module mode", but still emitted a warning telling users to use -m

• Fixes an issue where modal.runner.deploy_app() didn't work when called from within a running (remote) Modal Function

• Introduces an -m flag to modal run, modal shell, modal serve and modal deploy, which indicates that the modal app/function file is specified using python "module syntax" rather than a file path. In the future this will be a required flag when using module syntax.

  Old syntax:

  modal run my_package/modal_main.py
  modal run my_package.modal_main

  New syntax (note the -m on the second line):

  modal run my_package/modal_main.py
  modal run -m my_package.modal_main

• Passing App.lookup an invalid name now raises an error. App names may contain only alphanumeric characters, dashes, periods, and underscores, must be shorter than 64 characters, and cannot conflict with App ID strings.

• Fixes a bug where sandboxes returned from Sandbox.list() were not snapshottable even if they were created with _experimental_enable_snapshot.

• modal.FunctionCall is now available in the top-level modal namespace. We recommend referencing the class this way instead of using the the fully-qualified modal.functions.FunctionCall name.

• Function.web_url will now return None (instead of raising an error) when the Function is not a web endpoint

• Deprecate the GPU classes (gpu=A100(...) etc) in favor of just using strings (gpu="A100" etc)

• Adds a pending deprecation warning when looking up class methods using Function.from_name, e.g. Function.from_name("some_app", "SomeClass.some_method"). The recommended way to reference methods of classes is to look up the class instead: RemoteClass = Cls.from_name("some_app", "SomeClass")

• Fixes an issue introduced in 0.73.19 that prevented access to GPUs during image builds

• When using a parameterized class (with at least one modal.parameter() specified), class instantiation with an incorrect construction signature (wrong arguments or types) will now fail at the .remote() calling site instead of container startup for the called class.

• Fixed the status message shown in terminal logs for ephemeral Apps to accurately report the number of active containers.

• Warns users if the modal.Image of a Function/Cls doesn't include all the globally imported "local" modules (using .add_local_python_source()), and the user hasn't explicitly set an include_source value of True/False. This is in preparation for an upcoming deprecation of the current "auto mount" logic.

• Modal functions, methods and entrypoints can now accept variable-length arguments to skip Modal's default CLI parsing. This is useful if you want to use Modal with custom argument parsing via argparse or HfArgumentParser. For example, the following function can be invoked with modal run my_file.py --foo=42 --bar="baz":

  import argparse
  
  @app.function()
  def train(*arglist):
      parser = argparse.ArgumentParser()
      parser.add_argument("--foo", type=int)
      parser.add_argument("--bar", type=str)
      args = parser.parse_args(args = arglist)

• modal run now runs a single local entrypoints/function in the selected module. If exactly one local entrypoint or function exists in the selected module, the user doesn't have to qualify the runnable in the modal run command, even if some of the module's referenced apps have additional local entrypoints or functions. This partially restores "auto-inferred function" functionality that was changed in v0.72.48.

• Introduces an include_source argument in the App.function and App.cls decorators that let users configure which class of python packages are automatically included as source mounts in created modal functions/classes (what we used to call "automount" behavior). This will supersede the MODAL_AUTOMOUNT configuration value which will eventually be deprecated. As a convenience, the modal.App constructor will also accept an include_source argument which serves as the default for all the app's functions and classes.

  The include_source argument accepts the following values:

  • True (default in a future version of Modal) Automatically includes the Python files of the source package of the function's own home module, but not any other local packages. Roughly equivalent ot MODAL_AUTOMOUNT=0 in previous versions of Modal.
  • False - don't include any local source. Assumes the function's home module is importable in the container environment through some other means (typically added to the provided modal.Image's Python environment).
  • None (the default) - use current soon-to-be-deprecated automounting behavior, including source of all first party packages that are not installed into site-packages locally.

• Minor change to MODAL_AUTOMOUNT=0: When running/deploying using a module path (e.g. modal run mypak.mymod), all non .pyc files of the source package (mypak in this case) are now included in the function's container. Previously, only the function's home .py module file + any __init__.py files in its package structure were included. Note that this is only for MODAL_AUTOMOUNT=0. To get full control over which source files are included with your functions, you can set include_source=False on your function (see above) and manually specify the files to include using the ignore argument to Image.add_local_python_source.

• Deprecated .lookup methods on Modal objects. Users are encouraged to use .from_name instead. In most cases this will be a simple name substitution. See the 1.0 migration guide for more information.

• Fixes bug introduced in v0.72.48 where modal run didn't work with files having global Function.from_name()/Function.lookup()/Cls.from_name()/Cls.lookup() calls.

• Fixes a CLI bug where you couldn't reference functions via a qualified app, e.g. mymodule::{app_variable}.{function_name}.
• The modal run, modal serve and modal shell commands get more consistent error messages in cases where the passed app or function reference isn't resolvable to something that the current command expects.
• Removes the deprecated __getattr__, __setattr__, __getitem__ and __setitem__ methods from modal.App

• Introduced a new public method, .hydrate, for on-demand hydration of Modal objects. This method replaces the existing semi-public .resolve method, which is now deprecated.

• The Image returned by Sandbox.snapshot_filesystem now has object_id and other metadata pre-assigned rather than require loading by subsequent calls to sandboxes or similar to set this data.

• Adds a new oidc_auth_role_arn field to CloudBucketMount for using OIDC authentication to create the mountpoint.

• No longer prints a warning if app.include re-includes an already included function (warning is still printed if another function with the same name is included)

• Internal refactor of the modal.object module. All entities except Object from that module have now been moved to the modal._object "private" module.

• The @modal.build decorator is now deprecated. For storing large assets (e.g. model weights), we now recommend using a modal.Volume over writing data to the modal.Image filesystem directly.

• Fixes bug introduced in v0.72.9 where modal run SomeClass.some_method would incorrectly print a deprecation warning.

• Added an environment_name parameter to the App.run context manager.

• Fixes a bug introduced in v0.72.2 when specifying add_python="3.9" in Image.from_registry.

• The default behaviorImage.from_dockerfile() and image.dockerfile_commands() if no parameter is passed to ignore will be to automatically detect if there is a valid dockerignore file in the current working directory or next to the dockerfile following the same rules as dockerignore does using docker commands. Previously no patterns were ignored.

• FilePatternMatcher has a new constructor from_file which allows you to read file matching patterns from a file instead of having to pass them in directly, this can be used for Image methods accepting an ignore parameter in order to read ignore patterns from files.

• Modal Volumes can now be renamed via the CLI (modal volume rename) or SDK (modal.Volume.rename).

• Adds Image.from_id, which returns an Image object from an existing image id.

• Sandboxes now support fsnotify-like file watching:

from modal.file_io import FileWatchEventType

app = modal.App.lookup("file-watch", create_if_missing=True)
sb = modal.Sandbox.create(app=app)
events = sb.watch("/foo")
for event in events:
    if event.type == FileWatchEventType.Modify:
        print(event.paths)

• The sandbox filesystem API now accepts write payloads of sizes up to 1 GiB.

• Image.from_dockerfile() and image.dockerfile_commands() now auto-infer which files need to be uploaded based on COPY commands in the source if context_mount is omitted. The ignore= argument to these methods can be used to selectively omit files using a set of glob patterns.

• You can now point modal launch vscode at an arbitrary Dockerhub base image:

  modal launch vscode --image=nvidia/cuda:12.4.0-devel-ubuntu22.04

• You can now run GPU workloads on Nvidia L40S GPUs:

  @app.function(gpu="L40S")
  def my_gpu_fn():
      ...

• Fixed a bug introduced in v0.68.39 that changed the exception type raise when the target object for .from_name/.lookup methods was not found.

• Standardized terminology in .from_name/.lookup/.delete methods to use name consistently where label and tag were used interchangeably before. Code that invokes these methods using label= as an explicit keyword argument will issue a deprecation warning and will break in a future release.

• The internal deprecation_error and deprecation_warning utilities have been moved to a private namespace

• Sandboxes now support additional filesystem commands mkdir, rm, and ls.

app = modal.App.lookup("sandbox-fs", create_if_missing=True)
sb = modal.Sandbox.create(app=app)
sb.mkdir("/foo")
with sb.open("/foo/bar.txt", "w") as f:
    f.write("baz")
print(sb.ls("/foo"))

• Two previously-introduced deprecations are now enforced and raise an error:
  • The App.spawn_sandbox method has been removed in favor of Sandbox.create
  • Sandbox.create now requires an App object to be passed

• The modal run CLI now has a --write-result option. When you pass a filename, Modal will write the return value of the entrypoint function to that location on your local filesystem. The return value of the function must be either str or bytes to use this option; otherwise, an error will be raised. It can be useful for exercising a remote function that returns text, image data, etc.

Adds an ignore parameter to our Image add_local_dir and copy_local_dir methods. It is similar to the condition method on Mount methods but instead operates on a Path object. It takes either a list of string patterns to ignore which follows the dockerignore syntax implemented in our FilePatternMatcher class, or you can pass in a callable which allows for more flexible selection of files.

Usage:

img.add_local_dir(
  "./local-dir", 
  remote_path="/remote-path", 
  ignore=FilePatternMatcher("**/*", "!*.txt") # ignore everything except files ending with .txt
)

img.add_local_dir(
  ...,
  ignore=~FilePatternMatcher("**/*.py") # can be inverted for when inclusion filters are simpler to write
)

img.add_local_dir(
  ...,
  ignore=["**/*.py", "!module/*.py"] # ignore all .py files except those in the module directory
)

img.add_local_dir(
  ...,
  ignore=lambda fp: fp.is_relative_to("somewhere") # use a custom callable
)

which will add the ./local-dir directory to the image but ignore all files except .txt files

Adds the requires_proxy_auth parameter to web_endpoint, asgi_app, wsgi_app, and web_server decorators. Requests to the app will respond with 407 Proxy Authorization Required if a webhook token is not supplied in the HTTP headers. Protects against DoS attacks that will unnecessarily charge users.

• Cls.from_name(...) now works as a lazy alternative to Cls.lookup() that doesn't perform any IO until a method on the class is used for a .remote() call or similar

• Fixed a bug introduced in v0.67.47 that suppressed console output from the modal deploy CLI.

We're removing support for .spawn()ing generator functions.

• Sandboxes now support a new filesystem API. The open() method returns a FileIO handle for native file handling in sandboxes.

app = modal.App.lookup("sandbox-fs", create_if_missing=True)
sb = modal.Sandbox.create(app=app)

with sb.open("test.txt", "w") as f:
  f.write("Hello World\n")

f = sb.open("test.txt", "rb")
print(f.read())

• modal container exec and modal shell now work correctly even when a pseudoterminal (PTY) is not present. This means, for example, that you can pipe the output of these commands to a file:

  modal shell -c 'uv pip list' > env.txt

• It is now possible to delete named NetworkFileSystem objects via the CLI (modal nfs delete ...) or API (modal.NetworkFileSystem.delete(...))

• Sandboxes now support filesystem snapshots. Run Sandbox.snapshot_filesystem() to get an Image which can be used to spawn new Sandboxes.

• Adds Image.add_local_python_source which works similarly to the old and soon-to-be-deprecated Mount.from_local_python_packages but for images. One notable difference is that the new add_local_python_source only includes .py-files by default

• Image build functions that use a functools.wraps decorator will now have their global variables included in the cache key. Previously, the cache would use global variables referenced within the wrapper itself. This will force a rebuild for Image layers defined using wrapped functions.

• Fixed a bug introduced in v0.67.0 where it was impossible to call modal.Cls methods when passing a list of requested GPUs.

• Fixed a bug that executes the wrong method when a Modal Cls overrides a @modal.method inherited from a parent.

• Fixed a bug where pointing modal run at a method on a Modal Cls would fail if the method was inherited from a parent.

New minor client version 0.67.x comes with an internal data model change for how Modal creates functions for Modal classes. There are no breaking or backwards-incompatible changes with this release. All forward lookup scenarios (.lookup() of a 0.67 class from a pre 0.67 client) as well as backwards lookup scenarios (.lookup() of a pre 0.67 class from a 0.67 client) work, except for a 0.62 client looking up a 0.67 class (this maintains our current restriction of not being able to lookup a 0.63+ class from a 0.62 client).

• modal config set-environment will now raise if the requested environment does not exist.

• The modal launch CLI now accepts a --detach flag to run the App in detached mode, such that it will persist after the local client disconnects.

• Adds Image.add_local_file(..., copy=False) and Image.add_local_dir(..., copy=False) as a unified replacement for the old Image.copy_local_*() and Mount.add_local_* methods.

• Removed the aiostream package from the modal client library dependencies.

Sandbox.exec now accepts arguments text and bufsize for streaming output, which controls text output and line buffering.

• Modal no longer supports Python 3.8, which has reached its official EoL.

• Escalates stuck input cancellations to container death. This prevents unresponsive user code from holding up resources.
• Input timeouts no longer kill the entire container. Instead, they just cancel the timed-out input, leaving the container and other concurrent inputs running.

• Fixed issue in modal serve where files used in Image.copy_* commands were not watched for changes

• Sandbox.exec can now accept timeout, workdir, and secrets. See the Sandbox.create function for context on how to use these arguments.

• Removed the interactive parameter from function and cls decorators. This parameter has been deprecated since May 2024. Instead of specifying Modal Functions as interactive, use modal run --interactive to activate interactive mode.

• The checkpointing_enabled option, deprecated in March 2024, has now been removed.

• Output from Sandbox.exec can now be directed to /dev/null, stdout, or stored for consumption. This behavior can be controlled via the new StreamType arguments.

• Fixed a bug where the Image.imports context manager would not correctly propagate ImportError when using a modal.Cls.

• Fixed an issue where modal run would pause for 10s before exiting if there was a failure during app creation.

• The modal container list CLI command now shows the containers within a specific environment: the active profile's environment if there is one, otherwise the workspace's default environment. You can pass --env to list containers in other environments.

• Fixed modal serve not showing progress when reloading apps on file changes since v0.63.79.

• Fix a regression introduced in client version 0.64.209, which affects client authentication within a container.

• Fixed a bug where Queue.put and Queue.put_many would throw queue.Full even if timeout=None.

• The previously-deprecated --confirm flag has been removed from the modal volume delete CLI. Use --yes to force deletion without a confirmation prompt.

• Passing wait_for_response=False in Modal webhook decorators is no longer supported. See the docs for alternatives.

• When writing to a StreamWriter that has already had EOF written, a ValueError is now raised instead of an EOFError.

• Memory snapshotting can now be used with parametrized functions.

• StreamWriters now accept strings as input.

• Fixed a bug where App rollbacks would not restart a schedule that had been removed in an intervening deployment.

• The modal shell CLI command now takes a container ID, allowing you to shell into a running container.

• modal shell --cmd now can be shortened to modal shell -c. This means you can use it like modal shell -c "uname -a" to quickly run a command within the remote environment.

• The Image.conda, Image.conda_install, and Image.conda_update_from_environment methods are now fully deprecated. We recommend using micromamba (via Image.micromamba and Image.micromamba_install) instead, or manually installing and using conda with Image.run_commands when strictly necessary.

• Breaking Change: Sandbox.tunnels() now returns a Dict rather than a List. This dict is keyed by the container's port, and it returns a Tunnel object, just like modal.forward does.

• modal.Function and modal.Cls now support specifying a list of GPU configurations, allowing the Function's container pool to scale across each GPU configuration in preference order.

• The deprecated _experimental_boost argument is now removed. (Deprecated in late July.)

• Sandboxes can now be created without an entrypoint command. If they are created like this, they will stay alive up until their set timeout. This is useful if you want to keep a long-lived sandbox and execute code in it later.

• Sandboxes now have a cidr_allowlist argument, enabling controlled access to certain IP ranges. When not used (and with block_network=False), the sandbox process will have open network access.

Introduce an experimental API to allow users to set the input concurrency for a container locally.

• Creating sandboxes without an associated App is deprecated. If you are spawning a Sandbox outside a Modal container, you can lookup an App by name to attach to the Sandbox:

  app = modal.App.lookup('my-app', create_if_missing=True)
  modal.Sandbox.create('echo', 'hi', app=app)

• App handles can now be looked up by name with modal.App.lookup(name). This can be useful for associating Sandboxes with Apps:

  app = modal.App.lookup("my-app", create_if_missing=True)
  modal.Sandbox.create("echo", "hi", app=app)

• The default timeout for modal.Image.run_function has been lowered to 1 hour. Previously it was 24 hours.

• Fixes an issue that could cause containers using enable_memory_snapshot=True on Python 3.9 and below to shut down prematurely.

• Added support for ASGI lifespan protocol:

  @app.function()
  @modal.asgi_app()
  def func():
      from fastapi import FastAPI, Request
  
      def lifespan(wapp: FastAPI):
          print("Starting")
          yield {"foo": "bar"}
          print("Shutting down")
  
      web_app = FastAPI(lifespan=lifespan)
  
      @web_app.get("/")
      def get_state(request: Request):
          return {"message": f"This is the state: {request.state.foo}"}
  
      return web_app

  which enables support for gradio>=v4 amongst other libraries using lifespans

• Sandboxes now support port tunneling. Ports can be exposed via the open_ports argument, and a list of active tunnels can be retrieved via the .tunnels() method.

• Fixed a regression in modal launch to resume displaying output when starting the container.

• Introduces new dataclass-style syntax for class parametrization (see updated docs)

  @app.cls()
  class MyCls:
      param_a: str = modal.parameter()
  
  MyCls(param_a="hello")  # synthesized constructor

• The new syntax enforces types (str or int for now) on all parameters

• When the new syntax is used, any web endpoints (web_endpoint, asgi_app, wsgi_app or web_server) on the app will now also support parametrization through the use of query parameters matching the parameter names, e.g. https://myfunc.modal.run/?param_a="hello in the above example.

• The old explicit __init__ constructor syntax is still allowed, but could be deprecated in the future and doesn't work with web endpoint parametrization

• Added a modal app rollback CLI command for rolling back an App deployment to a previous version.

• Commands in the modal app CLI now accept an App name as a positional argument, in addition to an App ID:

  modal app history my-app
  

  Accordingly, the explicit --name option has been deprecated. Providing a name that can be confused with an App ID will also now raise an error.

• Updated type stubs using generics to allow static type inferrence for functions calls, e.g. function.remote(...).

• ContainerProcess handles now support wait() and poll(), like Sandbox objects

• Added support for dynamic batching. Functions or class methods decorated with @modal.batched will now automatically batch their invocations together, up to a specified max_batch_size. The batch will wait for a maximum of wait_ms for more invocations after the first invocation is made. See guide for more details.

  @app.function()
  @modal.batched(max_batch_size=4, wait_ms=1000)
  async def batched_multiply(xs: list[int], ys: list[int]) -> list[int]:
      return [x * y for x, y in zip(xs, xs)]
  
  @app.cls()
  class BatchedClass():
      @modal.batched(max_batch_size=4, wait_ms=1000)
      async def batched_multiply(xs: list[int], ys: list[int]) -> list[int]:
          return [x * y for x, y in zip(xs, xs)]

  The batched function is called with individual inputs:

  await batched_multiply.remote.aio(2, 3)

• Sandboxes now have an exec() method that lets you execute a command inside the sandbox container. exec returns a ContainerProcess handle for input and output streaming.

  sandbox = modal.Sandbox.create("sleep", "infinity")
  
  process = sandbox.exec("bash", "-c", "for i in $(seq 1 10); do echo foo $i; sleep 0.5; done")
  
  for line in process.stdout:
      print(line)

• Removed support for the undocumented modal.apps.list_apps() function, which was internal and not intended to be part of public API.

• Removed client check for CPU core request being at least 0.1, deferring to server-side enforcement.

• Volumes can now be mounted to an ad hoc modal shell session:

  modal shell --volume my-vol-name
  

  When the shell starts, the volume will be mounted at /mnt/my-vol-name. This may be helpful for shell-based exploration or manipulation of volume contents.

  Note that the option can be used multiple times to mount additional models:

  modal shell --volume models --volume data
  

• App deployment events are now atomic, reducing the risk that a failed deploy will leave the App in a bad state.

• The _experimental_boost argument can now be removed. Boost is now enabled on all modal Functions.

• Setting _allow_background_volume_commits is no longer necessary and has been deprecated. Remove this argument in your decorators.

• Image layers defined with a @modal.build method will now include the values of any class variables that are referenced within the method as part of the layer cache key. That means that the layer will rebuild when the class variables change or are overridden by a subclass.

• Fixed an error when running @modal.build methods that was introduced in v0.63.19

• Fixed bug where self.method.local() would re-trigger lifecycle methods in classes

• Adds Cls.lookup() backwards compatibility with classes created by clients prior to v0.63.

  Important: When updating (to >=v0.63) an app with a Modal class that's accessed using Cls.lookup() - make sure to update the client of the app/service using Cls.lookup() first, and then update the app containing the class being looked up.

• Fixed a bug introduced in 0.63.0 that broke modal.Cls.with_options

• Adds warning about future deprecation of retries for generators. Retries are being deprecated as they can lead to nondetermistic generator behavior.

• Fixed a bug in Volume.copy_files() where some source paths may be ignored if passed as bytes.
• Volume.read_file, Volume.read_file_into_fileobj, Volume.remove_file, and Volume.copy_files can no longer take both string or bytes for their paths. They now only accept str.

• Fixes issue with Cls.lookup not working (at all) after upgrading to v0.63.0. Note: this doesn't fix the cross-version lookup incompatibility introduced in 0.63.0.

• Changes how containers are associated with methods of @app.cls()-decorated Modal "classes".

  Previously each @method and web endpoint of a class would get its own set of isolated containers and never run in the same container as other sibling methods. Starting in this version, all @methods and web endpoints will be part of the same container pool. Notably, this means all methods will scale up/down together, and options like keep_warm and concurrency_limit will affect the total number of containers for all methods in the class combined, rather than individually.

  Version incompatibility warning: Older clients (below 0.63) can't use classes deployed by new clients (0.63 and above), and vice versa. Apps or standalone clients using Cls.lookup(...) to invoke Modal classes need to be upgraded to version 0.63 at the same time as the deployed app that's being called into.

• keep_warm for classes is now an attribute of the @app.cls() decorator rather than individual methods.

• Added support for mounting Volume or CloudBucketMount storage in Image.run_function. Note that this is typically not necessary, as data downloaded during the Image build can be stored directly in the Image filesystem.

• It is now an error to create or lookup Modal objects (Volume, Dict, Secret, etc.) with an invalid name. Object names must be shorter than 64 characters and may contain only alphanumeric characters, dashes, periods, and underscores. The name check had inadvertently been removed for a brief time following an internal refactor and then reintroduced as a warning. It is once more a hard error. Please get in touch if this is blocking access to your data.

• The modal app list command now reports apps created by modal app run or modal app serve as being in an "ephemeral" state rather than a "running" state to reduce confusion with deployed apps that are actively processing inputs.

• All modal CLI commands now accept -e as a short-form of --env

• Added support for entrypoint and shell for custom containers: Image.debian_slim().entrypoint([]) can be used interchangeably with .dockerfile_commands('ENTRYPOINT []'), and .shell(["/bin/bash", "-c"]) can be used interchangeably with .dockerfile_commands('SHELL ["/bin/bash", "-c"]')

• Fix an issue with @web_server decorator not working on image builder version 2023.12

• @web_server endpoints can now return HTTP headers of up to 64 KiB in length. Previously, they were limited to 8 KiB due to an implementation detail.

• modal deploy now accepts a --tag optional parameter that allows you to specify a custom tag for the deployed version, making it easier to identify and manage different deployments of your app.

• web_endpoints now have the option to include interactive SwaggerUI/redoc docs by setting docs=True
• web_endpoints no longer include an OpenAPI JSON spec route by default

• modal.Function now supports requesting ephemeral disk (SSD) via the new ephemeral_disk parameter. Intended for use in doing large dataset ingestion and transform.

• modal.Volume background commits are now enabled by default when using spawn_sandbox.

• The modal app stop CLI command now accepts a --name (or -n) option to stop an App by name rather than by ID.

• Background committing on modal.Volume mounts is now default behavior.

• Added a modal container stop CLI command that will kill an active container and reassign its current inputs.

• modal.CloudBucketMount now supports writing to Google Cloud Storage buckets.

• Using memory= to specify the type of modal.gpu.A100 is deprecated in favor of size=. Note that size accepts a string type ("40GB" or "80GB") rather than an integer, as this is a request for a specific variant of the A100 GPU.

• Added a version flag to the modal.Volume API and CLI, allow opting in to a new backend implementation.

• Fixed a bug where other functions weren't callable from within an asgi_app or wsgi_app constructor function and side effects of @enter methods weren't available in that scope.

• Disabling background commits on modal.Volume volumes is now deprecated. Background commits will soon become mandatory behavior.

• Deprecated wait_for_response=False on web endpoints. See the docs for alternatives.

• A deprecation warning is now raised when using modal.Stub, which has been renamed to modal.App. Additionally, it is recommended to use app as the variable name rather than stub, which matters when using the automatic app discovery feature in the modal run CLI command.

• Added a --stream-logs flag to modal deploy that, if True, begins streaming the app logs once deployment is complete.

• Added support for looking up a deployed App by its deployment name in modal app logs

• Added validation that App name, if provided, is a string.

• The @app.function decorator now raises an error when it is used to decorate a class (this was always invalid, but previously produced confusing behavior).

• The modal app list output has been improved in several ways:
  • Persistent storage objects like Volumes or Dicts are no longer included (these objects receive an app ID internally, but this is an implementation detail and subject to future change). You can use the dedicated CLI for each object (e.g. modal volume list) instead.
  • For Apps in a stopped state, the output is now limited to those stopped within the past 2 hours.
  • The number of tasks running for each App is now shown.

• Added the region parameter to the modal.App.function and modal.App.cls decorators. This feature allows the selection of specific regions for function execution. Note that it is available only on some plan types. See our blog post for more details.

• Added deprecation warnings when using Python 3.8 locally or in a container. Python 3.8 is nearing EOL, and Modal will be dropping support for it soon.

• Deprecated the Image.conda constructor and the Image.conda_install / Image.conda_update_from_environment methods. Conda-based images had a number of tricky issues and were generally slower and heavier than images based on micromamba, which offers a similar featureset and can install packages from the same repositories.
• Added the spec_file parameter to allow Image.micromamba_install to install dependencies from a local file. Note that micromamba supports conda yaml syntax along with simple text files.

• Added a deprecation warning when object names are invalid. This applies to Dict, NetworkFileSystem, Secret, Queue, and Volume objects. Names must be shorter than 64 characters and may contain only alphanumeric characters, dashes, periods, and underscores. These rules were previously enforced, but the check had inadvertently been dropped in a recent refactor. Please update the names of your objects and transfer any data to retain access, as invalid names will become an error in a future release.

• Added a command-line interface for interacting with modal.Queue objects. Run modal queue --help in your terminal to see what is available.

• Added a command-line interface for interacting with modal.Dict objects. Run modal dict --help in your terminal to see what is available.

• Secret.from_dotenv now accepts an optional filename keyword argument:

  @app.function(secrets=[modal.Secret.from_dotenv(filename=".env-dev")])
  def run():
      ...

• Passing a glob ** argument to the modal volume get CLI has been deprecated — instead, simply download the desired directory path, or / for the entire volume.
• Volume.listdir() no longer takes trailing glob arguments. Use recursive=True instead.
• modal volume get and modal nfs get performance is improved when downloading a single file. They also now work with multiple files when outputting to stdout.
• Fixed a visual bug where modal volume get on a single file will incorrectly display the destination path.

• Improved feedback for deserialization failures when objects are being transferred between local / remote environments.

• Added Dict.delete and Queue.delete as API methods for deleting named storage objects:

  import modal
  modal.Queue.delete("my-job-queue")

• Deprecated invoking Volume.delete as an instance method; it should now be invoked as a static method with the name of the Volume to delete, as with the other methods.

• The modal.Dict object now implements a keys/values/items API. Note that there are a few differences when compared to standard Python dicts:
  • The return value is a simple iterator, whereas Python uses a dictionary view object with more features.
  • The results are unordered.
• Additionally, there was no key data stored for items added to a modal.Dict prior to this release, so empty strings will be returned for these entries.

• We are introducing modal.App as a replacement for modal.Stub and encouraging the use of "app" terminology over "stub" to reduce confusion between concepts used in the SDK and the Dashboard. Support for modal.Stub will be gradually deprecated over the next few months.

• Specifying a hard memory limit for a modal.Function is now supported. Pass a tuple of memory=(request, limit). Above the limit, which is specified in MiB, a Function's container will be OOM killed.

• modal.CloudBucketMount now supports read-only access to Google Cloud Storage

• Iterators passed to Function.map() and similar parallel execution primitives are now executed on the main thread, preventing blocking iterators from possibly locking up background Modal API calls, and risking task shutdowns.

• The return type of Volume.listdir(), Volume.iterdir(), NetworkFileSystem.listdir(), and NetworkFileSystem.iterdir() is now a FileEntry dataclass from the modal.volume module. The fields of this data class are the same as the old protobuf object returned by these methods, so it should be mostly backwards-compatible.

• Cloudflare R2 bucket support added to modal.CloudBucketMount

• When Volume reloads fail due to an open file, we now try to identify and report the relevant path. Note that there may be some circumstances in which we are unable to identify the specific file blocking a reload and will report a generic error message in that case.

• Values in the modal.toml config file that are spelled as 0, false, "False", or "false" will now be coerced in Python toFalse, whereas previously only "0" (as a string) would have the intended effect.

• Fixed a recent regression that caused functions using modal.interact() to crash.

• Queue methods put, put_many, get, get_many and len now support an optional partition argument (must be specified as a kwarg). When specified, users read and write from new partitions of the queue independently. partition=None corresponds to the default partition of the queue.

• User can now mount S3 buckets using Requester Pays. This can be done with CloudBucketMount(..., requester_pays=True).

• Raise an error on @web_server(startup_timeout=0), which is an invalid configuration.

• The .new() method has now been deprecated on all Modal objects. It should typically be replaced with .from_name(...) in Modal app code, or .ephemeral() in scripts that use Modal
• Assignment of Modal objects to a Stub via subscription (stub["object"]) or attribute (stub.object) syntax is now deprecated. This syntax was only necessary when using .new().

• Fixed a bug where images based on micromamba could fail to build if requesting Python 3.12 when a different version of Python was being used locally.

• The Sandbox's LogsReader is now an asynchronous iterable. It supports the async for statement to stream data from the sandbox's stdout/stderr.

@stub.function()
async def my_fn():
    sandbox = stub.spawn_sandbox(
      "bash", 
      "-c", 
      "while true; do echo foo; sleep 1; done"
    )
    async for message in sandbox.stdout:
        print(f"Message: {message}")

• Add the @web_server decorator, which exposes a server listening on a container port as a web endpoint.

• Allow users to write to the Sandbox's stdin with StreamWriter.

@stub.function()
def my_fn():
    sandbox = stub.spawn_sandbox(
        "bash",
        "-c",
        "while read line; do echo $line; done",
    )
    sandbox.stdin.write(b"foo\\n")
    sandbox.stdin.write(b"bar\\n")
    sandbox.stdin.write_eof()
    sandbox.stdin.drain()
    sandbox.wait()

• Fixed an bug where Mount was failing to include symbolic links.

When called from within a container, modal.experimental.stop_fetching_inputs() causes it to gracefully exit after the current input has been processed.

• The @wsgi_app() decorator now uses a different backend based on a2wsgi that streams requests in chunks, rather than buffering the entire request body.

• Stubs/apps can now be "composed" from several smaller stubs using stub.include(...). This allows more ergonomic setup of multi-file Modal apps.

• The Image.extend method has been deprecated. This is a low-level interface and can be replaced by other Image methods that offer more flexibility, such as Image.from_dockerfile, Image.dockerfile_commands, or Image.run_commands.

• Fixes modal volume put to support uploading larger files, beyond 40 GiB.

• Modal containers now display a warning message if lingering threads are present at container exit, which prevents runner shutdown.

• Bug fix: Stopping an app while a container's @exit() lifecycle methods are being run no longer interrupts the lifecycle methods.
• Bug fix: Worker preemptions no longer interrupt a container's @exit() lifecycle method (until 30 seconds later).
• Bug fix: Async @exit() lifecycle methods are no longer skipped for sync functions.
• Bug fix: Stopping a sync function with allow_concurrent_inputs>1 now actually stops the container. Previously, it would not propagate the signal to worker threads, so they would continue running.
• Bug fix: Input-level cancellation no longer skips the @exit() lifecycle method.
• Improve stability of container entrypoint against race conditions in task cancellation.

• Fix issue with pdm where all installed packages would be automounted when using package cache (MOD-2485)

• For modal functions/classes with concurrency_limit < keep_warm, we'll raise an exception now. Previously we (silently) respected the concurrency_limit parameter.

modal run --interactive or modal run -i run the app in "interactive mode". This allows any remote code to connect to the user's local terminal by calling modal.interact().

@stub.function()
def my_fn(x):
    modal.interact()

    x = input()
    print(f"Your number is {x}")

This means that you can dynamically start an IPython shell if desired for debugging:

@stub.function()
def my_fn(x):
    modal.interact()

    from IPython import embed
    embed()

For convenience, breakpoints automatically call interact():

@stub.function()
def my_fn(x):
    breakpoint()

• Image.run_function now allows you to pass args and kwargs to the function. Usage:

def my_build_function(name, size, *, variant=None):
    print(f"Building {name} {size} {variant}")


image = modal.Image.debian_slim().run_function(
    my_build_function, args=("foo", 10), kwargs={"variant": "bar"}
)

• Mounted packages are now deduplicated across functions in the same stub
• Mounting of local Python packages are now marked as such in the mount creation output, e.g. PythonPackage:my_package
• Automatic mounting now includes packages outside of the function file's own directory. Mounted packages are mounted in /root/

• Most errors raised through usage of the CLI will now print a simple error message rather than showing a traceback from inside the modal library.
• Tracebacks originating from user code will include fewer frames from within modal itself.
• The new MODAL_TRACEBACK environment variable (and traceback field in the Modal config file) can override these behaviors so that full tracebacks are always shown.

• Fixed a bug that could cause cls-based functions to to ignore timeout signals.

• volume get performance is improved for large (> 100MB) files

• Support for function parameters in methods decorated with @exit has been deprecated. Previously, exit methods were required to accept three arguments containing exception information (akin to __exit__ in the context manager protocol). However, due to a bug, these arguments were always null. Going forward, @exit methods are expected to have no parameters.

• Function calls can now be cancelled without killing the container running the inputs. This allows new inputs by different function calls to the same function to be picked up immediately without having to cold-start new containers after cancelling calls.

• An InvalidError is now raised when a lifecycle decorator (@build, @enter, or @exit) is used in conjunction with @method. Previously, this was undefined and could produce confusing failures.

• Reduced the amount of context for frames in modal's CLI framework when showing a traceback.

• The "dunder method" approach for class lifecycle management (__build__, __enter__, __exit__, etc.) is now deprecated in favor of the modal @build, @enter, and @exit decorators.

• In modal token new and modal token set, the --no-no-verify flag has been removed in favor of a --verify flag. This remains the default behavior.

• Fixes a regression from 0.57.40 where @enter methods used a separate event loop.

• Adds a new environment variable/config setting, MODAL_FORCE_BUILD/force_build, that coerces all images to be built from scratch, rather than loaded from cache.

• The @enter() lifecycle method can now be used to run additional setup code prior to function checkpointing (when the class is decorated with stub.cls(enable_checkpointing=True). Note that there are currently some limitations on function checkpointing:
  • Checkpointing only works for CPU memory; any GPUs attached to the function will not available
  • Networking is disabled while the checkpoint is being created
• Please note that function checkpointing is still a beta feature.

• Fixed an issue with displaying deprecation warnings on Windows systems.

• Modal client deprecation warnings are now highlighted in the CLI

• Fixes a regression in container scheduling. Users on affected versions (0.57.5—0.57.15) are encouraged to upgrade immediately.

• The legacy image_python_version config option has been removed. Use the python_version= parameter on your image definition instead.

• Adds support for mounting an S3 bucket as a volume.

• Support for an implicit 'default' profile is now deprecated. If you have more than one profile in your Modal config file, one must be explicitly set to active (use modal profile activate or edit your .modal.toml file to resolve).
• An error is now raised when more than one profile is set to active.

• Improve error message when generator functions are called with .map(...).

• Greatly improved streaming performance of generators and WebSocket web endpoints.
• Breaking change: You cannot use .map() to call a generator function. (In previous versions, this merged the results onto a single stream, but the behavior was undocumented and not widely used.)
• Incompatibility: Generator outputs are now on a different internal system. Modal code on client versions before 0.57 cannot trigger deployed functions with .remote_gen() that are on client version 0.57, and vice versa.

Note that in version 0.56 and prior, Modal used a different numbering system for patch releases.

• When using modal token new or model token set, the profile containing the new token will now be activated by default. Use the --no-activate switch to update the modal.toml file without activating the corresponding profile.

• The modal profile list output now indicates when the workspace is determined by a token stored in environment variables.

• Variadic parameters (e.g. *args and **kwargs) can now be used in scheduled functions as long as the function doesn't have any other parameters without a default value

• modal container exec's --no-tty flag has been renamed to --no-pty.

• The singular form of the secret parameter in Stub.function, Stub.cls, and Image.run_function has been deprecated. Please update your code to use the plural form instead:secrets=[Secret(...)].

• In modal profile list, the user's GitHub username is now shown as the name for the "Personal" workspace.

• The modal token new and modal token set commands now create profiles that are more closely associated with workspaces, and they have more explicit profile activation behavior:
  • By default, these commands will create/update a profile named after the workspace that the token points to, rather than a profile named "default"
  • Both commands now have an --activate flag that will activate the profile associated with the new token
  • If no other profiles exist at the time of creation, the new profile will have its active metadata set to True
• With these changes, we are moving away from the concept of a "default" profile. Implicit usage of the "default" profile will be deprecated in a future update.

• Adds tty support to modal container exec for fully-interactive commands. Example: modal container exec [container-id] /bin/bash

• The modal profile list command now shows the workspace associated with each profile.

• Mount.from_local_python_packages now places mounted packages at /root in the Modal runtime by default (used to be /pkg). To override this behavior, the function now takes a remote_dir: Union[str, PurePosixPath] argument.

• The Modal client library is now compatible with Python 3.12, although there are a few limitations:

  • Images that use Python 3.12 without explicitly specifing it through python_version or add_python will not build properly unless the modal client is also running on Python 3.12.
  • The conda and microconda base images currently do not support Python 3.12 because an upstream dependency is not yet compatible.

• gpu.A100 class now supports specifying GiB memory configuration using a size: str parameter. The memory: int parameter is deprecated.

• You can now execute commands in running containers with modal container exec [container-id] [command].

• The modal cli now works more like the python cli in regard to script/module loading:
  • Running modal my_dir/my_script.py now puts my_dir on the PYTHONPATH.
  • modal my_package.my_module will now mount to /root/my_package/my_module.py in your Modal container, regardless if using automounting or not (and any intermediary __init__.py files will also be mounted)

• Modal now uses the current profile if MODAL_PROFILE is set to the empty string.

• Dropped support for building Python 3.7 based modal.Images. Python 3.7 is end-of-life since late June 2023.

• modal.Stub.function now takes a block_network argument.

• modal.Stub now takes a volumes argument for setting the default volumes of all the stub's functions, similarly to the mounts and secrets argument.

• modal serve: Setting MODAL_LOGLEVEL=DEBUG now displays which files cause an app reload during serve

• modal run cli command now properly propagates --env values to object lookups in global scope of user code