modal

library1.5.4pypypi✓ verified 26d ago

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.

devops ai-ml workflow

pip install modal

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · MODAL

modal

devopspythonv1.5.4

Install

7.4s avg

Import

2261ms

Disk

58MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.5.4 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 2.642s · 57.6MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 7.4s · import 1.880s · 60MB

58MB installed

● package 58MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

App

✓ import modal app = modal.App()

✗ import modal stub = modal.Stub()

modal.Stub was renamed to modal.App in v0.x. All tutorials using Stub() are outdated and will raise AttributeError.

fastapi_endpoint

✓ @modal.fastapi_endpoint()

✗ @modal.web_endpoint()

modal.web_endpoint renamed to modal.fastapi_endpoint in v0.73.89 / v1.0. Old decorator still works but is deprecated.

concurrent

✓ @modal.concurrent(max_inputs=10)

✗ @app.function(allow_concurrent_inputs=10)

allow_concurrent_inputs parameter replaced by @modal.concurrent decorator in v1.0.

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)

modal --version

Debug

Known issues

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

fix

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

affects: < 0.55.0

breakingmodal.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.

affects: < 1.0.0

breakingAutomounting 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').

affects: < 1.0.0

breakingAutoscaler 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.

affects: < 0.73.76

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.

affects: < 1.0.0

deprecatedImage.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.

affects: < 0.72.11

deprecatedmodal.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().

affects: < 0.73.89

gotchaModal 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.

affects: all

gotchamodal.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.

affects: >= 0.75.0

gotchaPip 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'.

affects: all

Errors

Common errors & fixes

modal: command not found

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.

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

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.

ModuleNotFoundError: No module named 'modAL'

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`.

ModuleNotFoundError: No module named 'your_local_package'

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')`.

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

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.

Upgrade

Version history

1.5.4latest on PyPI · released Aug 12, 2026

Audit

Dependencies

aiohttprequiredAsync HTTP transport used internally.

grpclibrequiredgRPC communication with Modal backend.

synchronicityrequiredModal's own library for bridging sync/async. Installed automatically.

fastapioptionalRequired when using modal.fastapi_endpoint decorator for web endpoints.

Agent activity

25 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/modal-labs/modal-client ↗

packagehttps://pypi.org/project/modal/ ↗

homepagehttps://modal.com ↗

docshttps://modal.com/docs ↗