Configure Databricks app execution with app.yaml

The app.yaml file in a Databricks app defines how your app runs. If your app requires a different entry point or environment-specific configuration, you can include this optional file in your project to override the default behavior.

You can use the .yaml or .yml file extension. This file must be located in the root of your project directory.

Supported settings

The app.yaml file supports the following settings.

Setting Type Description
command sequence Use this setting when you require a custom command to run your app. By default, Azure Databricks runs Python apps using the command python <my-app.py>, where <my-app.py> is the first .py file (in alphabetical order) in your app's root directory. If your app includes a package.json with a start script, the default command is npm run start. See Deployment logic.
Because Azure Databricks doesn't run the command in a shell, environment variables defined outside the app configuration aren't available to your app. The one exception is DATABRICKS_APP_PORT, which is substituted with the actual port number in the command at runtime. If your app requires additional parameters to run, use the env structure.
This setting is optional.
env list Azure Databricks automatically sets several default environment variables in the app runtime environment. This top-level key defines an optional list of additional environment variables to pass to your app. Each variable can use a hardcoded value or reference an external source, such as a secret or database entry.
The valid items in the list are:
  • name: The name of the environment variable.
  • One of:

This setting is optional.
health_check map Defines an HTTP endpoint that Azure Databricks checks before it marks a deployment as successful. The valid keys are:
  • path: The path to request, such as /health. Must start with /.
  • timeout_seconds: How long to wait for the endpoint to respond successfully, in seconds. The default and maximum value is 300.

See Configure a deployment health check.
This setting is optional.

Configure a deployment health check

By default, Azure Databricks marks a deployment as successful as soon as your app process starts, even if the app isn't ready to serve requests yet. Add a health_check setting so that Azure Databricks waits until your app is ready before it completes the deployment.

When a health check is configured, Azure Databricks sends HTTP GET requests to path on your app after the app starts, and repeats them until the endpoint returns a 2xx status code or timeout_seconds elapses. The health check runs each time the app is deployed or started.

  • If the endpoint returns a 2xx status code, the deployment succeeds and the new version begins to serve traffic.
  • If the endpoint doesn't return a 2xx status code before the timeout, or if the app process exits, the deployment fails. The deployment logs include the last status code or error that the health check received.

What happens to the previous version after a failed health check depends on the app type:

  • Horizontally scaled apps: The previous version continues to serve traffic. See Horizontal scaling for Databricks apps.
  • Standard apps: Azure Databricks stops the previous version before it starts the new one, so the app stops after a failed health check. Fix the issue and redeploy.

The following example waits up to 60 seconds for the /health endpoint to return a 2xx status code:

command: ['python', 'app.py']
health_check:
  path: '/health'
  timeout_seconds: 60

Example app.yaml for a Streamlit app

The following app.yaml file shows how to configure a Streamlit app. It uses a custom command to start the app with streamlit run, reads the SQL warehouse ID from an app resource, and sets a usage tracking flag. The valueFrom field requires a SQL warehouse resource with the key sql-warehouse. See Add a SQL warehouse resource to a Databricks app.

command: ['streamlit', 'run', 'app.py']
env:
  - name: 'DATABRICKS_WAREHOUSE_ID'
    valueFrom: 'sql-warehouse'
  - name: 'STREAMLIT_GATHER_USAGE_STATS'
    value: 'false'

Use a setup like this if your app depends on a specific compute resource, such as a SQL warehouse, or requires certain environment variables to control runtime behavior.

Example app.yaml for a Flask app

This example shows how to configure a Flask app using the Gunicorn server. The command setting specifies the Gunicorn startup parameters, and the env section sets the path to a Unity Catalog volume as an environment variable.

command:
  - gunicorn
  - app:app
  - -w
  - 4
env:
  - name: 'VOLUME_URI'
    value: '/Volumes/catalog-name/schema-name/dir-name'

Use this approach when your app needs a production-ready WSGI server like Gunicorn and when it depends on data stored in a Unity Catalog volume or another environment-specific path.

Additional resources

  • Last updated on