scientific-skills/modal/references/api_reference.md
The main unit of deployment. Groups related functions.
app = modal.App("my-app")
| Method | Description |
|---|---|
app.function(**kwargs) | Decorator to register a function |
app.cls(**kwargs) | Decorator to register a class |
app.local_entrypoint() | Decorator for local entry point |
A serverless function backed by an autoscaling container pool.
| Method | Description |
|---|---|
.remote(*args) | Execute in the cloud (sync) |
.local(*args) | Execute locally |
.spawn(*args) | Execute async, returns FunctionCall |
.map(inputs) | Parallel execution over inputs |
.starmap(inputs) | Parallel execution with multiple args |
.from_name(app, fn) | Reference a deployed function |
.update_autoscaler(**kwargs) | Dynamic scaling update |
A serverless class with lifecycle hooks.
@app.cls(gpu="L40S")
class MyClass:
@modal.enter()
def setup(self): ...
@modal.method()
def run(self, data): ...
@modal.exit()
def cleanup(self): ...
| Decorator | Description |
|---|---|
@modal.enter() | Container startup hook |
@modal.exit() | Container shutdown hook |
@modal.method() | Expose as callable method |
@modal.parameter() | Class-level parameter |
Defines the container environment.
| Method | Description |
|---|---|
.debian_slim(python_version=) | Debian base image |
.from_registry(tag) | Docker Hub image |
.from_dockerfile(path) | Build from Dockerfile |
.micromamba(python_version=) | Conda/mamba base |
.uv_pip_install(*pkgs) | Install with uv (recommended) |
.pip_install(*pkgs) | Install with pip |
.pip_install_from_requirements(path) | Install from file |
.apt_install(*pkgs) | Install system packages |
.run_commands(*cmds) | Run shell commands |
.run_function(fn) | Run Python during build |
.add_local_dir(local, remote) | Add directory |
.add_local_file(local, remote) | Add single file |
.add_local_python_source(module) | Add Python module |
.env(dict) | Set environment variables |
.imports() | Context manager for remote imports |
Distributed persistent file storage.
vol = modal.Volume.from_name("name", create_if_missing=True)
| Method | Description |
|---|---|
.from_name(name) | Reference or create a volume |
.commit() | Force immediate commit |
.reload() | Refresh to see other containers' writes |
Mount: @app.function(volumes={"/path": vol})
Legacy shared storage (superseded by Volume).
Secure credential injection.
| Method | Description |
|---|---|
.from_name(name) | Reference a named secret |
.from_dict(dict) | Create inline (dev only) |
.from_dotenv() | Load from .env file |
Usage: @app.function(secrets=[modal.Secret.from_name("x")])
Access in function: os.environ["KEY"]
schedule = modal.Cron("0 9 * * *") # Cron syntax
schedule = modal.Period(hours=6) # Fixed interval
Usage: @app.function(schedule=modal.Cron("..."))
| Decorator | Description |
|---|---|
@modal.fastapi_endpoint() | Simple FastAPI endpoint |
@modal.asgi_app() | Full ASGI app (FastAPI, Starlette) |
@modal.wsgi_app() | Full WSGI app (Flask, Django) |
@modal.web_server(port=) | Custom web server |
| Decorator | Description |
|---|---|
@modal.concurrent(max_inputs=) | Handle multiple inputs per container |
@modal.batched(max_batch_size=, wait_ms=) | Dynamic input batching |
| String | GPU |
|---|---|
"T4" | NVIDIA T4 16GB |
"L4" | NVIDIA L4 24GB |
"A10" | NVIDIA A10 24GB |
"L40S" | NVIDIA L40S 48GB |
"A100-40GB" | NVIDIA A100 40GB |
"A100-80GB" | NVIDIA A100 80GB |
"H100" | NVIDIA H100 80GB |
"H100!" | H100 (no auto-upgrade) |
"H200" | NVIDIA H200 141GB |
"B200" | NVIDIA B200 192GB |
"B200+" | B200 or B300, B200 price |
"H100:4" | 4x H100 |
| Command | Description |
|---|---|
modal setup | Authenticate |
modal run <file> | Run local entrypoint |
modal serve <file> | Dev server with hot reload |
modal deploy <file> | Production deployment |
modal app list | List deployed apps |
modal app stop <name> | Stop an app |
modal volume create <name> | Create volume |
modal volume ls <name> | List volume files |
modal volume put <name> <file> | Upload to volume |
modal volume get <name> <file> | Download from volume |
modal secret create <name> K=V | Create secret |
modal secret list | List secrets |
modal secret delete <name> | Delete secret |
modal token set | Set auth token |