Modal logo
IntroductionCustom container images Defining ImagesUsing existing container imagesFast pull from registryGPUs and other resources GPU accelerationUsing CUDA on ModalReserving CPU and memoryScaling out Scaling outInput concurrencyBatch processingJob queuesDynamic batching (beta)Multi-node clusters (beta)Deployment Apps, Functions, and entrypointsManaging deploymentsInvoking deployed functionsContinuous deploymentRunning untrusted code in FunctionsModal Sandboxes SandboxesRunning commandsNetworking and securityFile accessSnapshotsModal NotebooksSecrets and environment variables SecretsEnvironment variablesScheduling and cron jobsWeb endpoints Web endpointsStreaming endpointsWeb endpoint URLsRequest timeoutsProxy Auth TokensNetworking TunnelsProxies (beta)Cluster networkingData sharing and storage Passing local dataVolumesStoring model weightsCloud bucket mountsDictsQueuesDataset ingestionPerformance Cold start performanceMemory SnapshotHigh-performance LLM inferenceGeographic latencyReliability and robustness Failures and retriesPreemptionTimeoutsGPU healthTroubleshootingSecurity and privacyIntegrations Using OIDC to authenticate with external servicesConnecting Modal to your Datadog accountConnecting Modal to your OpenTelemetry providerOkta SSOCustom SAML SSOSlack notifications (beta)Workspace & account settings WorkspacesEnvironmentsModal user account setupService usersBillingOther topics JavaScript/Go SDKsModal 1.0 migration guideFile and project structureDeveloping and debuggingDeveloping Modal code with LLMsJupyter notebooksAsynchronous API usageGlobal variablesRegion selectionContainer lifecycle hooksParametrized functionsS3 Gateway endpointsGPU Metrics

Snapshots

Sandboxes support snapshotting, allowing you to save your Sandbox’s state and restore it later. This is useful for:

  • Reducing startup latency
  • Creating custom environments for your Sandboxes to run in
  • Backing up your Sandbox’s state for debugging
  • Running large-scale experiments with the same initial state
  • Branching your Sandbox’s state to test different code changes independently

Modal currently supports three different kinds of Sandbox snapshots:

  1. Filesystem Snapshots
  2. Directory Snapshots (Beta)
  3. Memory Snapshots (Alpha)

Filesystem Snapshots 

Filesystem Snapshots are copies of the Sandbox’s filesystem at a given point in time. These Snapshots are Images and can be used to create new Sandboxes.

To create a Filesystem Snapshot, you can use the Sandbox.snapshot_filesystem() method:

Filesystem Snapshots are optimized for performance: they are calculated as the difference from your base image, so only modified files are stored. Restoring a Filesystem Snapshot utilizes the same infrastructure we use to get fast cold starts for your Sandboxes.

Filesystem Snapshots will generally persist indefinitely.

Directory Snapshots (Beta) 

Directory Snapshots allow you to snapshot a specific directory within a running Sandbox. The resulting snapshot is an Image that can then be mounted into already-running Sandbox, which can be useful for:

  • Updating system dependencies separately from application code: Base dependencies can be updated by starting a new Sandbox from an updated base Image, and then mounting in the application code.
  • Using warm pools in combination with snapshots: For use cases that benefit from a warm pool of Sandboxes to reduce start-up latency, the first initialization can now happen in the warm pool without losing the ability to restore application-specific code at a later point in time.
  • Speeding up processes inside the Sandbox: Files in mounted Images are prioritized for pre-loading, which can speed up any processes that use those files.

Note that the directory snapshots API is experimental, meaning it is subject to change.

Usage 

Use _experimental_mount_image to mount a Modal Image at a directory path (pass None for an empty mount), and _experimental_snapshot_directory to snapshot the directory:

You can only snapshot directories that have been mounted using _experimental_mount_image. Contact us at support@modal.com if you have any questions!

Persistence 

Directory snapshots are currently persisted for 30 days after they were last created or used. For longer persisting snapshots, use Filesystem Snapshots.

Memory Snapshots (Alpha) 

🌱 Sandbox memory snapshots are in alpha.

Sandbox memory snapshots are copies of a Sandbox’s entire state, both in memory and on the filesystem. These Snapshots can be restored later to create a new Sandbox, which is an exact clone of the original Sandbox.

To snapshot a Sandbox, create it with _experimental_enable_snapshot set to True, and use the _experimental_snapshot method, which returns a SandboxSnapshot object:

Create a new Sandbox from the returned SandboxSnapshot with Sandbox._experimental_from_snapshot:

The new Sandbox will be a duplicate of your original Sandbox. All running processes will still be running, in the same state as when they were snapshotted, and any changes made to the filesystem will be visible.

You can retrieve the ID of any Sandbox Snapshot with snapshot.object_id . To restore from a snapshot by ID, first rehydrate the Snapshot with SandboxSnapshot.from_id and then restore from it:

Note that these methods are experimental, and we may change them in the future.

Re-snapshotting 

Modal supports creating a new snapshot from a restored Sandbox snapshot. To maintain the snapshot’s expiration window, the new snapshot inherits the expiration of its parent.

Continuing from the example code above, we demonstrate re-snapshotting:

Limitations 

Currently, Sandbox Memory Snapshots will expire 7 days after creation. For longer persisting snapshots, try Filesystem Snapshots.

Open TCP connections will be closed automatically when a Snapshot is taken, and will need to be reopened when the Snapshot is restored.

Snapshotting a sandbox will currently cause it to terminate. We intend to remove this limitation soon.

Sandboxes created with _experimental_enable_snapshot=True or restored from Snapshots cannot run with GPUs.

It is not possible to snapshot a sandbox while a Sandbox.exec command is still running. Furthermore, any background processes launched by a call to Sandbox.exec will not be properly restored after a snapshot.

Persisting Sandbox State 

To persist state across Sandbox sessions, you need to:

  1. Trigger the snapshot. Snapshots are triggered from outside the Sandbox, typically just before termination. A common pattern is to run an exec process inside the Sandbox and wait for it to exit. Once it does, the controller takes a snapshot and terminates the Sandbox.
  2. Store the snapshot ID. The object_id string must be persisted so you can restore from it later. This is typically keyed by a session or user ID, and can be stored in your database, an external key-value store, or a Modal Dict.

The following example shows this pattern. This code would typically run in a Modal Function or your own backend, orchestrating the Sandbox: