modal.App

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:

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

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

name

The user-provided name of the App.

app_id

Return the app_id of a running or stopped app.

description

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

lookup

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:

get_dashboard_url

run

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.

Example

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

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:

You can then run your script with:

deploy

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.

Examples:

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

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:

Then you can deploy your app with:

local_entrypoint

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.

Example

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

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, you can qualify the name of your app and 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":

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

function

Decorator to register a new Modal Function with this App.

cls

Decorator to register a new Modal Cls with this App.

include

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

set_tags

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

get_tags

Get the tags that are currently attached to the App.