Modal Classes and Lifecycle

Use this skill when using class-based Functions for stateful workloads, lifecycle management, or parametrization.

When to Use This Skill

• Loading an ML model once per container (not per request)
• Sharing state between method calls
• Running setup/teardown logic per container
• Creating separate container pools per parameter set (e.g., per user)
• Combining GPU inference with lifecycle hooks

Core Pattern: Class with Lifecycle

import modal

app = modal.App()

@app.cls(gpu="A100")
class Model:
    @modal.enter()
    def setup(self):
        self.model = load_model()

    @modal.method()
    def predict(self, prompt: str) -> str:
        return self.model(prompt)

    @modal.exit()
    def cleanup(self):
        del self.model

Calling

@app.local_entrypoint()
def main():
    model = Model()
    result = model.predict.remote("hello")

Lifecycle Hooks

@modal.enter()

Runs once when a container starts. Use for expensive initialization:

@modal.enter()
def setup(self):
    self.model = load_model("/models/llama")
    self.tokenizer = load_tokenizer()

@modal.exit()

Runs when a container shuts down. Use for cleanup:

@modal.exit()
def teardown(self):
    save_metrics(self.metrics)

@modal.exit() also runs on SIGTERM (preemption).

@modal.method()

Exposes a class method as an invokable Function:

@modal.method()
def predict(self, x):
    return self.model(x)

Parametrization

Create separate container pools per parameter combination:

@app.cls()
class Worker:
    user_id: str = modal.parameter()
    model_size: str = modal.parameter(default="small")

    @modal.enter()
    def setup(self):
        self.model = load_model(self.model_size)

    @modal.method()
    def process(self, data):
        return self.model(data)

Calling parametrized classes

w1 = Worker(user_id="alice", model_size="large")
w1.process.remote(data)  # runs in alice/large pool

w2 = Worker(user_id="bob")
w2.process.remote(data)  # runs in bob/small pool (separate containers)

Each unique parameter combination gets its own autoscaling pool.

with_options (Runtime Override)

Override class configuration dynamically:

Model = modal.Cls.from_name("my-app", "Model")
FastModel = Model.with_options(gpu="H100", max_containers=10)
FastModel().predict.remote("hello")

Stackable: Model.with_options(gpu="H100").with_options(scaledown_window=300)

Go SDK — Calling Deployed Classes

mc, _ := modal.NewClient()

// Reference a deployed class
cls, _ := mc.Cls.FromName(ctx, "my-app", "Model", nil)

// Create a parameterized instance
instance := cls.Create(map[string]any{"model_size": "large"})

// Call a method
result, _ := instance.Method("predict").Remote(ctx, []any{"hello"}, nil)

// Spawn async
call, _ := instance.Method("predict").Spawn(ctx, []any{"hello"}, nil)
later, _ := call.Get(ctx, nil)

TypeScript SDK — Calling Deployed Classes

import { ModalClient } from "modal";
const modal = new ModalClient();

// Reference a deployed class
const cls = await modal.cls.fromName("my-app", "Model");

// Create a parameterized instance
const instance = await cls.create({ model_size: "large" });

// Call a method
const result = await instance.method("predict").remote(["hello"]);

// Spawn async
const call = await instance.method("predict").spawn(["hello"]);
const later = await call.get();

Note: Go/TS SDKs can only call deployed classes — defining classes with lifecycle hooks (@modal.enter, @modal.exit) is Python-only.

Symptom Triage

"Model loads on every request"

• Use @modal.enter() to load once per container
• Move model loading from __init__ or method body to @modal.enter()

"Container shutdown is abrupt"

• Use @modal.exit() for graceful cleanup
• @modal.exit() receives SIGTERM on preemption

"Each user shares a container pool"

• Use modal.parameter() to create per-user pools
• Each unique parameter combination scales independently

Reference Map

• references/classes-and-methods.md — @app.cls, @modal.method, invocation patterns
• references/lifecycle-hooks.md — @modal.enter, @modal.exit, execution order
• references/parametrization.md — modal.parameter, per-user pools, with_options

Related Skills

• modal-servers — @app.server also uses @modal.enter/@modal.exit, but exposes HTTP to a port (no @modal.method)
• modal-scaling-performance — memory snapshots with @modal.enter(snap=True), concurrency, batching
• modal-parallel-execution — calling class methods via .remote / .map / .spawn

Guardrails

• @modal.enter() runs once per container, not once per input
• @modal.exit() is best-effort on container shutdown
• Parameters are limited to 16 KiB total
• Use @modal.method() (not @app.function()) for class methods
• @app.cls() replaces @app.function() for the class decorator
• Do not put @modal.method on an @app.server class — use modal-servers for port-based serving