Modal

1.3.3 verified Tue May 12 auth: yes python install: verified quickstart: verified

Serverless cloud infrastructure for AI workloads. Run Python functions on GPUs with sub-second cold starts. v1.0 released May 2025 with multiple breaking API changes. Rapid release cadence — multiple versions per week.

pip install modal

Common errors

error modal: command not found ↓

cause The Modal CLI executable is not in your system's PATH environment variable, meaning the shell cannot locate the command.

fix

Use python -m modal instead of modal for CLI commands, or reconfigure your system's environment variables to include the Python package executables in your PATH.

error AttributeError: type object 'Stub' has no attribute 'function' ↓

cause The `modal.Stub` class was renamed to `modal.App` in Modal v1.0, and directly referencing `modal.Stub` or its methods will now raise an AttributeError.

fix

Replace all instances of modal.Stub() with modal.App() in your code.

error ModuleNotFoundError: No module named 'modAL' ↓

cause This error often occurs when developers confuse the `modal-client` library (used for serverless cloud functions) with a different, similarly named active learning library called `modAL`.

fix

Ensure you are importing the correct library as import modal (for Modal Labs) and not from modAL.models import ActiveLearner or similar, which belongs to the modAL library. If you intend to use Modal Labs, ensure you have installed modal-client (or modal) and not modAL-python.

error ModuleNotFoundError: No module named 'your_local_package' ↓

cause Prior to Modal v1.0, local Python packages were 'automounted'. In v1.0 and later, local dependencies must be explicitly included in your Modal image definition.

fix

Add your local Python package to your Modal image using image.add_local_python_package('your_local_package_path') or image.add_local_python_source('your_local_source_directory').

error RuntimeError: CUDA driver initialization failed, you might not have a CUDA gpu. ↓

cause This error indicates an issue with the NVIDIA CUDA driver initialization on the GPU instance, which can be a flaky issue with certain L4 GPU types within Modal's fleet.

fix

While Modal is investigating a root cause fix, you can try re-running your job, as this might be a transient issue. Ensure your Modal Image has the necessary CUDA versions and drivers if you are building a custom image.

Warnings

breaking modal.Stub renamed to modal.App. Any code using modal.Stub() raises AttributeError on current versions. ↓

fix Replace all modal.Stub() with modal.App().

breaking modal.Mount removed from public API in v1.0. Passing mount= to @app.function or @app.cls raises TypeError. ↓

fix Use Image.add_local_file() or Image.add_local_dir() instead of modal.Mount.

breaking Automounting of local Python modules removed in v1.0. Remote containers no longer automatically include local imports. ↓

fix Explicitly add local dependencies with Image.add_local_python_source('your_module').

breaking Autoscaler parameters renamed in v1.0: keep_warm → min_containers, concurrency_limit → max_containers, container_idle_timeout → scaledown_window. ↓

fix Find-and-replace all three parameter names in function decorators.

breaking @modal.build decorator deprecated in v1.0. Using it for model weight downloads is no longer the recommended pattern. ↓

fix Use modal.Volume to store model weights instead. Mount the Volume to the framework's cache directory.

deprecated Image.copy_local_dir and Image.copy_local_file deprecated. Replaced by Image.add_local_dir and Image.add_local_file. ↓

fix Use Image.add_local_dir() / Image.add_local_file(). Pass copy=True if subsequent build steps need the files.

deprecated modal.web_endpoint renamed to modal.fastapi_endpoint. Old name still works but will be removed in a future v1.x release. ↓

fix Replace @modal.web_endpoint() with @modal.fastapi_endpoint().

gotcha Modal releases multiple versions per week including pre-release .devN builds. Unpinned installs in CI can pick up pre-release versions unexpectedly. ↓

fix Pin to a stable release in production: pip install modal==1.3.3. Avoid pip install modal --pre in automated environments.

gotcha modal.Dict values expire after 7 days of inactivity on the new backend (introduced May 2025). Previously created Dicts use the old backend with no expiry. ↓

fix Do not use modal.Dict for persistent storage. Use modal.Volume for data that must survive beyond 7 days of inactivity.

gotcha Pip output includes warnings about running as a root user and an available update. Running pip as root can lead to permission issues and conflicting behavior with the system package manager. ↓

fix It is recommended to use a virtual environment for pip operations or run pip as a non-root user. To update pip, run 'pip install --upgrade pip'.

Install

modal setup

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 2.50s 55.8M

3.10 slim (glibc) - - 2.08s 58M

3.11 alpine (musl) - - 2.75s 61.8M

3.11 slim (glibc) - - 1.84s 64M

3.12 alpine (musl) - - 2.54s 53.2M

3.12 slim (glibc) - - 1.98s 56M

3.13 alpine (musl) - - 2.32s 52.8M

3.13 slim (glibc) - - 1.89s 55M

3.9 alpine (musl) - - 1.52s 54.4M

3.9 slim (glibc) - - 0.53s 57M

Imports

App
wrong
```
import modal
stub = modal.Stub()
```
correct
```
import modal
app = modal.App()
```
modal.Stub was renamed to modal.App in v0.x. All tutorials using Stub() are outdated and will raise AttributeError.
fastapi_endpoint
wrong
```
@modal.web_endpoint()
```
correct
```
@modal.fastapi_endpoint()
```
modal.web_endpoint renamed to modal.fastapi_endpoint in v0.73.89 / v1.0. Old decorator still works but is deprecated.
concurrent
wrong
```
@app.function(allow_concurrent_inputs=10)
```
correct
```
@modal.concurrent(max_inputs=10)
```
allow_concurrent_inputs parameter replaced by @modal.concurrent decorator in v1.0.

Quickstart verified last tested: 2026-05-12

Deploy a GPU function to Modal. Run with: modal run script.py

import modal

app = modal.App()

@app.function(
    gpu="A10G",
    image=modal.Image.debian_slim().pip_install("torch")
)
def run_inference(prompt: str) -> str:
    import torch
    # your model code here
    return "result"

@app.local_entrypoint()
def main():
    result = run_inference.remote("hello")
    print(result)