Modal logo
Guide Introduction to Modal Getting started Functions Functions Invocation methods Function lookups Container lifecycle management Parametrized Functions Dynamic configuration Sandboxes Sandboxes Running commands Networking and security File access Snapshots Exit Snapshots BetaPricing and resources Sidecars BetaSecret injection BetaEndpoints Endpoints Supported models Shared Endpoints Dedicated Endpoints Endpoint candidates Endpoint integrations Training Quickstart Tinker-compatible API BetaMulti-node training Images Defining Images Using existing container images Named images Fast pull from registry GPUs and other resources GPU acceleration Using CUDA on Modal Configuring CPU, memory, and disk Scaling out Scaling out Input concurrency Batch processing Job queues Dynamic batching Multi-node Clusters Deployment Apps, Functions, and entrypoints Managing deployments Continuous deployment Scheduled Functions HTTP Applications Servers Sticky Sessions Web Functions Streaming endpoints Web Function URLs Request timeouts Proxy Tokens Networking Tunnels Proxies BetaCluster networking Data sharing and storage Passing local data Volumes Storing model weights Cloud bucket mounts Dicts Queues Dataset ingestion Secrets and environment variables Secrets Environment variables Performance Cold start performance Memory Snapshots High-performance LLM inference Reliability and robustness Failures and retries Preemption Timeouts GPU health Troubleshooting Security and privacy Security and privacy Data residency Customer-supplied encryption keys AlphaAudit logs Integrations Using OIDC to authenticate with external services Connecting Modal to your Datadog account Connecting Modal to your OpenTelemetry provider Okta SSO Microsoft Entra SSO Custom SAML SSO SCIM Integration Slack notifications BetaWorkspace & account settings Workspaces Environments Service users User groups Role-Based Access Control (RBAC) Billing Network egress billing Budgets Other topics Feature maturity Restricted Functions JavaScript/Go SDKs BetaModal 1.0 migration guide File and project structure Developing and debugging Jupyter notebooks Asynchronous API usage Global variables Region selection GPU Metrics Search syntax

Image builder migration guides

What changed in each image builder version, and what to check in your Image recipes before migrating.

2026.10 

2026.10 refreshes the base images and the Modal client dependencies, and builds the base layer of external images separately so that it stays cached when the rest of the recipe changes.

Requirements: Modal client 1.6.3 or later. Supported Python versions: 3.11 through 3.15, including the free-threaded 3.14t and 3.15t builds. Python 3.10 is no longer supported.

Debian 13 base images 

modal.Image.debian_slim and modal.Image.micromamba are based on Debian 13 (“trixie”) instead of Debian 12 (“bookworm”), so packages installed with apt_install resolve to the versions Debian 13 ships. micromamba moves to 2.9.

Updated client dependencies 

The client dependencies included in containers at runtime are updated, including protobuf 7 and grpclib 0.4.9, and no longer vary by Python version. As with 2025.06, they are deprioritized on the PYTHONPATH, so versions installed by your Image recipe take precedence.

Base layers of external images are cached separately 

For modal.Image.from_dockerfile, the FROM instruction of a single-stage Dockerfile is built as its own layer and reused by later builds that share the base image. This applies only when no instruction or parser directive precedes FROM; comments and whitespace before it are ignored.

For modal.Image.from_registry, the Python distribution requested with add_python= is added in a separate layer, so changing the Python version no longer invalidates the base layer.

2025.06 

2025.06 changes how the Modal client dependencies are included in containers, which should greatly reduce the risk of conflicts with your own dependencies.

Requirements: Modal client 1.1 or later. Supported Python versions: 3.10 through 3.15, including the free-threaded 3.14t and 3.15t builds.

Client dependencies are no longer installed in the Image 

Modal no longer installs its client dependencies within base Image layers. Instead, the client dependencies are included in containers at runtime in a location that is deprioritized on the PYTHONPATH relative to the environment’s site-packages. This has a few consequences when there are conflicts with the user’s Image recipe:

  • In cases where one of the Modal client dependencies is already present in a base Image layer (i.e., in the image provided to modal.Image.from_registry or the recipe provided to modal.Image.from_dockerfile), the version in the base Image will no longer be overridden by Modal’s version.
  • Any Modal client dependencies installed via a subsequent Image method will now always take precedence, whereas previously it would have been necessary to pin a desired version or force a reinstall to override Modal’s version.

External base images no longer require Python packaging tools 

For external base images (those using modal.Image.from_registry and modal.Image.from_dockerfile), Modal will also no longer force an install or upgrade of Python packaging tools (pip, uv, and wheel). This means that these methods can be used to provide external Images to a modal.Sandbox without that Image needing to have Python installed. Previously, Sandboxes implicitly required external Images to have a version of Python that is compatible with the Modal client, even though the client is not used inside of a Sandbox.

On the other hand, you may need to update your Image recipes if the external Image provides an outdated version of pip or if your recipe assumes that uv is available. Note that version 1.1 of the Modal client also adds first-class support for uv through modal.Image.uv_pip_install and modal.Image.uv_sync.

These changes should also provide more compatibility with Image recipes that activate a virtual environment, since the Modal client dependencies that are included at runtime should always be available as a fallback on the PYTHONPATH.

Otherwise, the set of client dependencies is largely the same as in version 2024.10, although version pins have been updated.

Sandboxes run the Image’s CMD by default 

Previously, modal.Sandbox.create would implicitly run sleep 48h when no other command was specified. With new Images, the Sandbox uses the Image’s CMD instruction instead. If using an Image with a short-lived CMD, it may be necessary to explicitly specify sleep 48h or similar when creating a Sandbox.

2024.10 

2024.10 removes several Python libraries (the entire fastapi stack, including pydantic, along with rich and its dependencies), leaves protobuf as an unpinned requirement for better compatibility with user applications, and adds support for Python 3.13. The images guide covers how to set the version for a Workspace or Environment.

Requirements: Modal client 0.65.41 or later. Supported Python versions: 3.10 through 3.13.

Paring back the default libraries lowers the risk of dependency conflicts and improves cold start times. Explicitly installing only what you need ensures leaner, more efficient Images.

If migrating directly from 2023.12 (the legacy version for all Workspaces created prior to November 2024), it is also worth reading the 2024.04 migration guide, as the changes are cumulative.

Removal of fastapi 

Removing fastapi from default container requirements affects all Functions using the @modal.web_endpoint decorator along with any Functions using the @modal.asgi_app decorator with a FastAPI application. These Functions now require fastapi to be explicitly installed. We recommend installing fastapi[standard] to enable key features.

For @modal.web_endpoint Functions, an error will be raised at deployment time if the Function does not have fastapi installed in its Image. For @modal.asgi_app Functions, we don’t assume that fastapi is necessary, so any errors would be deferred to runtime.

If your App uses multiple Images and constructs a FastAPI app in global scope, all Images will need to have fastapi installed. Alternatively, you can move the definition of the FastAPI app into a scope that will be executed only on relevant Images.

Removal of pydantic 

Similar to the case with FastAPI apps, any pydantic model definitions in global scope will be executed on all Images.

If upgrading directly from the 2023.12 image builder, note that older Images contained pydantic 1.x by default, whereas a fresh install will pull in pydantic 2.x. This may be relevant for Functions that accept or return pydantic types, as compatible versions would need to be used on both sides of the serialization / deserialization boundary.

Removal of rich 

The Modal CLI uses rich extensively, but it should not be necessary for operation of the Modal client in a container unless container-side code calls modal.enable_output.

Other removals 

The following is a complete list of packages removed relative to 2024.04:

  • Pygments
  • aiostream
  • annotated-types
  • anyio
  • fastapi
  • markdown-it-py
  • mdurl
  • pydantic
  • pydantic_core
  • python-multipart
  • rich
  • sniffio
  • starlette

2024.04 

2024.04 updates debian_slim to Debian 12 (“bookworm”), removes several Python libraries (including numpy, ipython, ddtrace, cloudpickle, and toml), updates fastapi to a version that supports pydantic 2.0, pins all remaining Python libraries, and includes uv by default. The images guide covers how to set the version for a Workspace or Environment.

Requirements: Supported Python versions: 3.10 through 3.12.

Update to pydantic version 

The 2.x series of pydantic included a number of breaking changes that may affect Apps previously using 1.x. Take note of whether your Image definition pinned other libraries on versions that would not be forward-compatible with pydantic 2.x.

When pydantic models are sent to or returned from a Function, or stored in the in-memory data structures (Dict and Queue), the object will be serialized in one context and deserialized in another. Compatible versions of pydantic need to be used on each side of this operation.

Removal of numpy 

PyTorch does not define numpy as an explicit dependency, but application code may transform torch tensors into numpy arrays or vice versa. When torch is imported without numpy installed, a warning is typically printed, but this may or may not indicate an actual problem.

While the previous image builder did not pin a specific version of numpy, older Images likely contained version 1.x, whereas a 2.x series has since been released with some breaking changes. As with pydantic, this may be relevant for inter-library compatibility in the container or for serialization / deserialization operations.

Changes to default Python version with Image.micromamba 

Previously, the default Python version used by Image.micromamba was hardcoded to “3.9”. Going forward, it will default to the same minor version as used on the local system, akin to the behavior of Image.debian_slim.

Other removals 

The following is the complete list of packages removed relative to 2023.12:

  • asgiref
  • asttokens
  • async-timeout
  • charset-normalizer
  • click
  • cloudpickle
  • commonmark
  • decorator
  • executing
  • fastprogress
  • importlib-metadata
  • ipython
  • jedi
  • matplotlib-inline
  • numpy
  • parso
  • pexpect
  • prompt-toolkit
  • ptyprocess
  • pure-eval
  • six
  • stack-data
  • tblib
  • toml
  • traitlets
  • typeguard
  • typer
  • types-certifi
  • types-toml
  • wcwidth
  • zipp

Upgrading 

Set the version for your Workspace on the image builder version settings page, or for a single Environment from its Environment settings. Your Images rebuild on the next deploy.