scientific-skills/modal/references/volumes.md
Volumes are Modal's distributed file system, optimized for write-once, read-many workloads like storing model weights and distributing them across containers.
Key characteristics:
vol = modal.Volume.from_name("my-volume", create_if_missing=True)
modal volume create my-volume
# v2 volume (beta)
modal volume create my-volume --version=2
vol = modal.Volume.from_name("my-volume", create_if_missing=True, version=2)
Mount volumes to functions via the volumes parameter:
vol = modal.Volume.from_name("model-store", create_if_missing=True)
@app.function(volumes={"/models": vol})
def use_model():
# Access files at /models/
with open("/models/config.json") as f:
config = json.load(f)
Mount multiple volumes:
weights_vol = modal.Volume.from_name("weights")
data_vol = modal.Volume.from_name("datasets")
@app.function(volumes={"/weights": weights_vol, "/data": data_vol})
def train():
...
@app.function(volumes={"/data": vol})
def save_results(results):
import json
import os
os.makedirs("/data/outputs", exist_ok=True)
with open("/data/outputs/results.json", "w") as f:
json.dump(results, f)
@app.function(volumes={"/data": vol})
def load_results():
with open("/data/outputs/results.json") as f:
return json.load(f)
@app.function(volumes={"/models": vol}, gpu="L40S")
def save_model():
import torch
model = train_model()
torch.save(model.state_dict(), "/models/checkpoint.pt")
@app.function(volumes={"/models": vol}, gpu="L40S")
def load_model():
import torch
model = MyModel()
model.load_state_dict(torch.load("/models/checkpoint.pt"))
return model
# List files
modal volume ls my-volume
modal volume ls my-volume /subdir/
# Upload files
modal volume put my-volume local_file.txt
modal volume put my-volume local_file.txt /remote/path/file.txt
# Download files
modal volume get my-volume /remote/file.txt local_file.txt
# Delete a volume
modal volume delete my-volume
Modal auto-commits volume changes in the background every few seconds and on container shutdown.
Force an immediate commit:
@app.function(volumes={"/data": vol})
def writer():
with open("/data/file.txt", "w") as f:
f.write("hello")
vol.commit() # Make immediately visible to other containers
See changes from other containers:
@app.function(volumes={"/data": vol})
def reader():
vol.reload() # Refresh to see latest writes
with open("/data/file.txt") as f:
return f.read()
v2 Volumes (beta) offer significant improvements:
| Feature | v1 | v2 |
|---|---|---|
| Max files | 500,000 | Unlimited |
| Concurrent writes | ~5 | Hundreds |
| Max file size | No limit | 1 TiB |
| Random access | Limited | Full support |
| HIPAA compliance | No | Yes |
| Hard links | No | Yes |
Enable v2:
vol = modal.Volume.from_name("my-vol-v2", create_if_missing=True, version=2)
vol = modal.Volume.from_name("model-weights", create_if_missing=True)
# Download once during image build
def download_weights():
from huggingface_hub import snapshot_download
snapshot_download("meta-llama/Llama-3-8B", local_dir="/models/llama3")
image = (
modal.Image.debian_slim()
.uv_pip_install("huggingface_hub")
.run_function(download_weights, volumes={"/models": vol})
)
@app.function(volumes={"/checkpoints": vol}, gpu="H100", timeout=86400)
def train():
for epoch in range(100):
train_one_epoch()
torch.save(model.state_dict(), f"/checkpoints/epoch_{epoch}.pt")
vol.commit() # Save checkpoint immediately
data_vol = modal.Volume.from_name("shared-data", create_if_missing=True)
@app.function(volumes={"/data": data_vol})
def preprocess():
# Write processed data
df.to_parquet("/data/processed.parquet")
@app.function(volumes={"/data": data_vol})
def analyze():
data_vol.reload() # Ensure we see latest data
df = pd.read_parquet("/data/processed.parquet")
return df.describe()
ephemeral_disk instead of Volumes