Key concepts in Databricks Apps

This article introduces the core concepts behind Databricks Apps, including how apps are structured, how they manage dependencies and state, how permissions work, and how apps interact with platform resources. Understanding these concepts helps when developing, deploying, and managing apps in your workspace.

App

A Databricks app is a web application that runs as a containerized service on the Databricks serverless platform. Developers use supported frameworks such as Streamlit, Dash, or Gradio to build apps that deliver interactive data or AI experiences within a Databricks workspace.

Each app includes its own configuration, identity, and isolated runtime environment. Because apps belong to a specific workspace, they can access workspace-level resources like SQL warehouses and account-level resources like Unity Catalog. Developers can also choose to share apps with users outside the workspace but within the same Databricks account.

Although the app container runs on the Databricks serverless infrastructure, the app itself can connect to both serverless and non-serverless resources. Conceptually, an app acts as a control plane service that hosts a web UI and accesses available Databricks data plane services. For more information, see the Databricks architecture overview.

To launch and manage apps, go to the Apps section in the workspace UI.

Template

An app template is a prebuilt scaffold that helps developers start building apps quickly using a supported framework. Each template includes a basic file structure, an app.yaml manifest, a requirements.txt file, and sample source code.

The app.yaml file defines the command to run the app (for example, streamlit run <app-name> for a Streamlit app), sets up local environment variables, and declares any required resources. The requirements.txt file lists additional Python packages to install with pip, alongside the default system environment and pre-installed packages. For more information, see Define environment variables in a Databricks app.

Developers can generate a new app from a template using the Databricks UI or CLI.

System environment and packages

Databricks Apps run in a pre-configured system environment managed by Databricks. For details, see Databricks Apps system environment.

To add additional Python packages, define them in the requirements.txt file included in your app template. During deployment, Databricks installs these packages into the app’s isolated runtime environment. If your requirements.txt includes a package that’s already pre-installed, the specified version overrides the default. See Manage dependencies for a Databricks app.

Each app has its own isolated environment to avoid dependency conflicts between apps. To ensure consistency across environments, you can pin specific package versions in requirements.txt.

App resources

App resources are Databricks-native services that an app depends on, such as SQL warehouses, model serving endpoints, jobs, secrets, or volumes. You declare these dependencies in the databricks.yml manifest using the resources field. Databricks supports the following resource types:

• SQL warehouse
• Job
• Model serving endpoint
• Genie space
• Secret
• Volume

To access Databricks services that don’t yet have a supported resource type, use a Unity Catalog–managed secret to securely inject credentials. See Secret management.

There are two stages to configuring app resources:

• Declaration (development) - Declare each required resource in the databricks.yml manifest. This defines which resources the app needs and what permissions it requires.
• Configuration (deployment) - During deployment, use the Databricks Apps UI to configure the declared resources with actual workspace-specific instances (for example, selecting a specific SQL warehouse).

This separation between declaration and configuration allows apps to be portable across environments. For example, you can deploy the same app code in a development workspace and link it to one SQL warehouse. In production, you can reuse the code and configure a different warehouse without making code changes. To support this, avoid hardcoding resource IDs or environment-specific values in your app.

Databricks enforces least-privilege access. Apps must use existing resources and can't create new ones. During deployment, workspace admins review and approve the app’s requested access to resources. The app’s service principal receives the necessary permissions, and the app developer must have permission to grant them.

To learn more, see Add resources to a Databricks app.

App status

An app can have one of the following statuses: Running, Stopped, Deploying, or Crashed.

• Running - The app is active and accessible. Databricks bills for the compute resources used while the app is running.
• Stopped - The app is not accessible and doesn't incur any costs. Databricks preserves the app's configuration and environment, so you can restart it without reconfiguring.
• Deploying - The app is starting up. It's not yet accessible and doesn't incur any charges during this stage.
• Crashed - The app failed to start or stopped unexpectedly. It's inaccessible and doesn't incur charges. You can view logs to troubleshoot and restart the app once the issue is resolved.

App state

App state includes any data or context that the app needs to persist across user sessions or interactions. Apps don't preserve in-memory state after restarts. Any data held in memory is lost when the app shuts down.

To maintain state between sessions or restarts, developers must store it externally. For example, an app can persist state using Databricks SQL (such as Delta tables), workspace files, or Unity Catalog volumes. Common use cases include caching query results, saving user preferences, or logging user actions across sessions.

App authentication and authorization

Databricks Apps uses OAuth 2.0 for authentication and access control. Each app has two complementary identities that determine how it authenticates and authorizes access to Databricks resources: app authorization and user authorization.

• App authorization - Databricks automatically creates a service principal for each app. This service principal acts as the app’s identity and is granted permissions by the app developer. All users of the app share this identity and have access to the same set of permissions. This model is useful for operations that don't depend on the individual user’s context, such as logging or system-level actions.

• User authorization - This model uses the app user’s identity to authenticate and authorize access. Users must belong to the Databricks account where the app is deployed. After signing in through single sign-on (SSO), the app can use the user's credentials to access governed resources like a SQL warehouse. This allows the app to respect the fine-grained permissions managed by Unity Catalog without granting those permissions to the app’s service principal.

Apps request specific OAuth scopes in their manifest to control which APIs and resources they can access. This flexible model supports enterprise-grade security and enables fine-grained access control.

For more information, see Configure authorization in a Databricks app.

App users

After deployment, app developers can share an app with users or groups by granting the CAN_USE or CAN_MANAGE permission on the app instance. Users don’t need to belong to the same workspace, but they must be part of the same Databricks account. To share with external users, first sync them into the account using your identity provider. For more information, see Sync users and groups from your identity provider using SCIM.

You can also distribute the same app across development, staging, and production environments using CI/CD pipelines and infrastructure as code. The centralized Apps UI helps users discover and launch apps that they’re authorized to use.