How to beginner · 3 min read

Modal distributed storage

Q: Modal distributed storage

Use modal.Storage to create distributed, persistent storage volumes accessible across Modal functions and containers. This storage supports file and directory operations and is automatically synchronized and durable across Modal's distributed infrastructure.

Quick answer

Use modal.Storage to create distributed, persistent storage volumes accessible across Modal functions and containers. This storage supports file and directory operations and is automatically synchronized and durable across Modal's distributed infrastructure.

PREREQUISITES

Python 3.8+
Modal account and CLI installed
pip install modal

Setup

Install the modal Python package and log in to your Modal account. This enables you to create and manage distributed storage volumes in your Modal applications.

bash

pip install modal
modal login

output

Collecting modal
  Downloading modal-1.x.x-py3-none-any.whl (xx kB)
Installing collected packages: modal
Successfully installed modal-1.x.x

Logging in to Modal...
Logged in successfully as user@example.com

Step by step

This example shows how to create a distributed storage volume, write a file to it, and read the file back from a Modal function.

python

import modal

# Create a Modal stub
stub = modal.Stub()

# Create or get a distributed storage volume named 'my-volume'
storage = modal.Storage.persisted("my-volume")

@stub.function()
def write_file():
    with storage.open("hello.txt", "w") as f:
        f.write("Hello from Modal distributed storage!")

@stub.function()
def read_file():
    with storage.open("hello.txt", "r") as f:
        content = f.read()
    print(content)

if __name__ == "__main__":
    write_file.call()
    read_file.call()

output

Hello from Modal distributed storage!

Common variations

Use modal.Storage.new() for ephemeral storage that resets on each run.
Mount storage volumes to containers using volumes={"/mnt/data": storage} in function decorators.
Use async Modal functions with @stub.function() and await for concurrent storage access.

python

import modal

stub = modal.Stub()
storage = modal.Storage.persisted("my-volume")

@stub.function(volumes={"/mnt/data": storage})
async def async_read():
    async with await modal.aopen("/mnt/data/hello.txt", "r") as f:
        content = await f.read()
    print(content)

if __name__ == "__main__":
    import asyncio
    asyncio.run(async_read.call())

output

Hello from Modal distributed storage!

Troubleshooting

If you see FileNotFoundError, ensure the file was written before reading and that the storage volume name matches.
For permission errors, verify your Modal account has access to the storage volume.
Storage volumes are global and persistent; deleting a volume requires Modal CLI or dashboard actions.

✅

Key Takeaways

Use modal.Storage.persisted() to create durable distributed storage volumes.
Mount storage volumes to Modal functions for seamless file access across containers.
Storage volumes synchronize automatically across Modal's distributed infrastructure.
Use modal.Storage.new() for ephemeral storage that resets each run.
Troubleshoot by verifying volume names, file existence, and Modal account permissions.

Verified 2026-04

Verify ↗