App

class App(object)

A Modal App is a group of functions and classes that are deployed together.

The app serves at least three purposes:

• A unit of deployment for functions and classes.
• Syncing of identities of (primarily) functions and classes across processes (your local Python interpreter and every Modal container active in your application).
• Manage log collection for everything that happens inside your code.

Registering functions with an app

The most common way to explicitly register an Object with an app is through the @app.function() decorator. It both registers the annotated function itself and other passed objects, like schedules and secrets, with the app:

import modal

app = modal.App()

@app.function(
    secrets=[modal.Secret.from_name("some_secret")],
    schedule=modal.Period(days=1),
)
def foo():
    pass

In this example, the secret and schedule are registered with the app.

__init__(self, name=None, *, tags=None, image=None, secrets=[], volumes={},
    include_source=True)

Construct a new app, optionally with default image, mounts, secrets, or volumes.

Parameters

Usage

image = modal.Image.debian_slim().pip_install(...)
secret = modal.Secret.from_name("my-secret")
volume = modal.Volume.from_name("my-data")
app = modal.App(image=image, secrets=[secret], volumes={"/mnt/data": volume})

name

name(self)

The user-provided name of the App.

Returns

The configured app name, if any.

app_id

app_id(self)

Return the app_id of a running or stopped app.

Returns

The app ID when the app has been deployed or run, otherwise None.

description

description(self)

The App's name, if available, or a fallback descriptive identifier.

Returns

Human-readable description string for the app.

lookup

lookup(name, *, client=None, environment_name=None, create_if_missing=False)

Look up an App with a given name, creating a new App if necessary.

Note that Apps created through this method will be in a deployed state, but they will not have any associated Functions or Classes. This method is mainly useful for creating an App to associate with a Sandbox.

Parameters

Returns

An App handle tied to the deployed app record.

Usage

app = modal.App.lookup("my-app", create_if_missing=True)
modal.Sandbox.create("echo", "hi", app=app)

get_dashboard_url

get_dashboard_url(self)

Get the dashboard URL for the App.

Returns

The dashboard URL for the App.

Usage

app = modal.App.lookup("my-app")
print(app.get_dashboard_url())

run

run(self, *, name=None, client=None, detach=False, interactive=False,
    environment_name=None)

Context manager that runs an ephemeral app on Modal.

Use this as the main entry point for your Modal application. All calls to Modal Functions should be made within the scope of this context manager, and they will correspond to the current App.

Note that you should not invoke this in global scope of a file where you have Modal Functions or Classes defined, since that would run the block when the Function or Cls is imported in your containers as well. If you want to run it as your entrypoint, consider protecting it with if __name__ == "__main__".

Parameters

Returns

Async context manager yielding this App while it is running.

Usage

with app.run():
    some_modal_function.remote()

To enable output printing (i.e., to see App logs), use modal.enable_output():

with modal.enable_output():
    with app.run():
        some_modal_function.remote()

Note that you should not invoke this in global scope of a file where you have Modal Functions or Classes defined, since that would run the block when the Function or Cls is imported in your containers as well. If you want to run it as your entrypoint, consider protecting it:

if __name__ == "__main__":
    with app.run():
        some_modal_function.remote()

You can then run your script with:

python app_module.py

deploy

deploy(self, *, name=None, environment_name=None, tag="", client=None,
    strategy="rolling")

Deploy the App so that it is available persistently.

Deployed Apps will be available for lookup or web-based invocations until they are stopped. Unlike with App.run, this method will return as soon as the deployment completes.

This method is a programmatic alternative to the modal deploy CLI command.

Unlike with App.run, Function logs will not stream back to the local client after the App is deployed.

Note that you should not invoke this method in global scope, as that would redeploy the App every time the file is imported. If you want to write a programmatic deployment script, protect this call so that it only runs when the file is executed directly.

Parameters

Returns

This app instance after deployment completes.

Usage

app = App("my-app")
app.deploy()

To enable output printing (i.e., to see build logs), use modal.enable_output():

app = App("my-app")
with modal.enable_output():
    app.deploy()

Unlike with App.run, Function logs will not stream back to the local client after the App is deployed.

Note that you should not invoke this method in global scope, as that would redeploy the App every time the file is imported. If you want to write a programmatic deployment script, protect this call so that it only runs when the file is executed directly. You can then run your script with:

if __name__ == "__main__":
    with modal.enable_output():
        app.deploy()

Then you can deploy your app with:

python app_module.py

local_entrypoint

local_entrypoint(self, _warn_parentheses_missing=None, *, name=None)

Decorate a function to be used as a CLI entrypoint for a Modal App.

These functions can be used to define code that runs locally to set up the app, and act as an entrypoint to start Modal functions from. Note that regular Modal functions can also be used as CLI entrypoints, but unlike local_entrypoint, those functions are executed remotely directly.

Note that an explicit app.run() is not needed, as an app is automatically created for you.

Parameters

Returns

A decorator that registers the wrapped callable as a local CLI entrypoint.

Usage

@app.local_entrypoint()
def main():
    some_modal_function.remote()

You can call the function using modal run directly from the CLI:

modal run app_module.py

Note that an explicit app.run() is not needed, as an app is automatically created for you.

Multiple entrypoints

If you have multiple local_entrypoint functions, qualify the name:

modal run app_module.py::app.some_other_function

Parsing arguments

If your entrypoint function take arguments with primitive types, modal run automatically parses them as CLI options. For example, the following function can be called with modal run app_module.py --foo 1 --bar "hello":

@app.local_entrypoint()
def main(foo: int, bar: str):
    some_modal_function.call(foo, bar)

Currently, str, int, float, bool, and datetime.datetime are supported. Use modal run app_module.py --help for more information on usage.

function

function(self, *, image=None, schedule=None, env=None, secrets=None, gpu=None,
    serialized=False, network_file_systems={}, volumes={}, cpu=None,
    memory=None, ephemeral_disk=None, min_containers=None, max_containers=None,
    buffer_containers=None, scaledown_window=None, proxy=None, retries=None,
    timeout=300, startup_timeout=None, name=None, is_generator=None, cloud=None,
    region=None, routing_region=None, nonpreemptible=False,
    enable_memory_snapshot=False, block_network=False,
    restrict_modal_access=False, single_use_containers=False, i6pn=None,
    include_source=None, experimental_options=None,
    _experimental_restrict_output=False, max_inputs=None)

Decorator to register a new Modal Function with this App.

Parameters

Returns

A decorator that registers the wrapped callable or partial as a Modal Function.

cls

cls(self, *, image=None, env=None, secrets=None, gpu=None, serialized=False,
    network_file_systems={}, volumes={}, cpu=None, memory=None,
    ephemeral_disk=None, min_containers=None, max_containers=None,
    buffer_containers=None, scaledown_window=None, proxy=None, retries=None,
    timeout=300, startup_timeout=None, cloud=None, region=None,
    routing_region=None, nonpreemptible=False, enable_memory_snapshot=False,
    block_network=False, restrict_modal_access=False,
    single_use_containers=False, i6pn=None, include_source=None,
    experimental_options=None, _experimental_restrict_output=False,
    max_inputs=None)

Decorator to register a new Modal Cls with this App.

Parameters

Returns

A decorator that registers the wrapped class or partial as a Modal Cls.

server

server(self, *, image=None, env=None, secrets=None, gpu=None, serialized=False,
    volumes={}, cpu=None, memory=None, ephemeral_disk=None,
    target_concurrency=None, min_containers=None, max_containers=None,
    buffer_containers=None, scaleup_window=None, scaledown_window=None,
    startup_timeout=30, name=None, port=8000, unauthenticated=False,
    h2_enabled=False, exit_grace_period=0, routing_region="us-east",
    compute_region=None, cloud=None, nonpreemptible=False, proxy=None,
    i6pn=None, enable_memory_snapshot=False, include_source=None,
    experimental_options=None)

Decorator to register a new Modal Server with this App.

Servers run HTTP servers that are started in a @modal.enter() method. Unlike @app.cls(), servers only expose HTTP endpoints and do not support .remote() method calls.

See the guide for more information.

Parameters

Usage

@app.server(port=8000, routing_region="us-east")
class MyServer:
    @modal.enter()
    def start(self):
        self.proc = subprocess.Popen(["python3", "-m", "http.server", "8000"])

    @modal.exit()
    def stop(self):
        self.proc.terminate()

include

include(self, /, other_app, inherit_tags=True)

Include another App's objects in this one.

Useful for splitting up Modal Apps across different self-contained files.

When inherit_tags=True any tags set on the other App will be inherited by this App (with this App's tags taking precedence in the case of conflicts).

Parameters

Returns

This app instance for chaining.

Usage

app_a = modal.App("a")
@app_a.function()
def foo():
    ...

app_b = modal.App("b")
@app_b.function()
def bar():
    ...

app_a.include(app_b)

@app_a.local_entrypoint()
def main():
    # use function declared on the included app
    bar.remote()

set_tags

set_tags(self, tags, *, client=None)

Attach key-value metadata to the App.

Tag metadata can be used to add organization-specific context to the App and can be included in billing reports and other informational APIs. Tags can also be set in the App constructor.

Any tags set on the App before calling this method will be removed if they are not included in the argument (i.e., this method does not have .update() semantics).

Parameters

get_tags

get_tags(self, *, client=None)

Get the tags that are currently attached to the App.

Parameters

Returns

Tags as a map from key to value.

logs

logs: AppLogsManager

Access logs for an App.

Use fetch() to read logs from a UTC time range, tail() to read the most recent logs, and stream() to follow new logs as they arrive.

See Also

• modal app logs: CLI access to logs for an App.

logs.fetch

fetch(self, *, since, until=None, source=None, search_text="")

Fetch App logs corresponding to the date range and filters.

Parameters

Yields

LogEntry objects in chronological order.

Usage

app = modal.App.lookup("my-app")

for entry in app.logs.fetch(
    since=datetime.now() - timedelta(hours=4),
    source="stdout",
):
    print(entry.message, end="")

logs.tail

tail(self, entries=100, *, source=None)

Fetch the most recent App logs.

Parameters

Yields

LogEntry objects in chronological order.

Usage

app = modal.App.lookup("my-app")

for entry in app.logs.tail(20):
    print(entry.message, end="")

logs.stream

stream(self, timeout=None)

Stream new App logs until the timeout is reached.

Parameters

Yields

LogEntry objects as they arrive.

Usage

app = modal.App.lookup("my-app")

for entry in app.logs.stream(timeout=60):
    print(entry.message, end="")