Manage Databricks apps using Databricks Asset Bundles

Databricks Apps lets you create secure data and AI applications on the Databricks platform that you can easily share with users. You can manage deployments of your apps using Databricks Asset Bundles. For more information about apps and bundles, see Databricks Apps and What are Databricks Asset Bundles?.

This article walks you through developing a Databricks app locally, then configuring a bundle to manage deployments of the app to the Databricks workspace using Databricks Asset Bundles.

tip

To initialize an example bundle with a Streamlit app, use the streamlit-app bundle template with the bundle init command:

Bash
databricks bundle init https://github.com/databricks/bundle-examples --template-dir contrib/templates/streamlit-app

Requirements

Your Databricks workspace and local development environment must meet the requirements for Databricks Apps. See Set up your Databricks Apps workspace and development environment.
Databricks CLI version 0.250.0 or above. To check your installed version of the Databricks CLI, run the command databricks -v. To install the Databricks CLI, see Install or update the Databricks CLI.

Create an app locally

First, create a Databricks app. Apps are developed in Python using popular frameworks, such as Dash or Gradio. You can build a Databricks app locally from scratch, create one in the Databricks workspace and then sync the files to your local machine, or get a Databricks sample app from GitHub.

To build an app from scratch:
1. Follow a quick start tutorial for a framework:
  - Dash
  - Flask
  - Gradio
  - Shiny
  - Streamlit
2. Add an app.yaml file to the root of your project to define how to run your main Python app. For example:
  
  For a Streamlit app:
  YAML
```
command: ['streamlit', 'run', 'app.py']
```
  Or for a Dash app:
  YAML
```
command: ['python', 'app.py']
```
To create an app in the workspace and sync it locally:
1. Follow the steps in Get started with Databricks Apps to create an app in the UI.
2. Create a local directory for the app and cd into it:
  Bash
```
mkdir hello-world-app
cd hello-world-app
```
3. Sync the app files locally. You can copy the databricks workspace export-dir command from the app installation page in the workspace UI and run it at your command line. For example:
  Bash
```
databricks workspace export-dir /Workspace/Users/someone@example.com/databricks_apps/hello-world_2025_05_09-17_43/hello-world-app .
```
  This downloads the app files in the workspace directory to the hello-world-app directory on your local machine.
To get a Databricks sample app from GitHub:
1. Clone the Databricks app templates GitHub repository:
  Bash
```
git clone https://github.com/databricks/app-templates
```
2. Choose one of the sample apps as a simple app project.

Add an existing app to an existing bundle

If you have a Databricks app in your workspace, and have an existing bundle that you want to add the app to, you can use the databricks bundle generate app command. This command generates a configuration file for the app and downloads all source code files for the app, and adds these to your bundle. For example:

Bash
databricks bundle generate app --existing-app-name hello-world-app

After you have generated the app configuration in your bundle, use the databricks bundle bind command to keep the app in the workspace and bundle in sync.

For more information about databricks bundle generate and databricks bundle bind, see bundle command group.

Develop and debug the app locally

Next, continue developing your app locally. Launch and debug the app using the databricks apps run-local command. This command starts an app proxy which is used to proxy requests to the app itself and injects necessary Databricks app-related headers.

To install all dependencies, prepare the virtual environment, and start the app and debugger, use the run-local command with the --prepare-environment and --debug options:
Bash
```
databricks apps run-local --prepare-environment --debug
```
This command uses uv to prepare the virtual environment and the debugger is based on debugpy.
Navigate to http://localhost:8001 to view your app.
Set breakpoints to debug your app. In Visual Studio Code, install the Python debugger, then select Run > Start Debugging and then Remote Attach.

The proxy starts on port 5678, but you can configure it using the --port option.

Deploy the app to the workspace

When you are ready to deploy your app to the workspace, add bundle configuration that creates the app, then deploy the bundle.

Create a file databricks.yml at the root of your app project. The Databricks CLI recognizes a folder with a databricks.yml file at its root as a bundle, which enables databricks bundle commands.

Copy and paste the following YAML into the databricks.yml file, substituting placeholder workspace and username values for your own:

YAML
bundle:
  name: hello_world_bundle

resources:
  apps:
    hello_world_app:
      name: 'hello-world-app'
      source_code_path: . # This assumes the app source code is at the root of the project.
      description: 'A Databricks app'

targets:
  dev:
    mode: development
    default: true
    workspace:
      host: https://myworkspace.cloud.databricks.com
  prod:
    mode: production
    workspace:
      host: https://myworkspace.cloud.databricks.com
      root_path: /Workspace/Users/someone@example.com/.bundle/${bundle.name}/${bundle.target}
    permissions:
      - user_name: someone@example.com
        level: CAN_MANAGE

Validate, then deploy the bundle. By default, this creates the app and bundle in the dev target in the workspace.
Bash
```
databricks bundle validate
databricks bundle deploy
```
Deploying a bundle doesn’t automatically deploy the app to compute. To deploy the app, use either the UI (from the app's page in the Databricks workspace) or the Databricks CLI (databricks apps deploy). See Deploy a Databricks app.

Use the bundle summary command to retrieve information about the deployed app:

Bash
databricks bundle summary

Output
Name: hello_world_bundle
Target: dev
Workspace:
  Host: https://myworkspace.cloud.databricks.com
  User: someone@example.com
  Path: /Workspace/Users/someone@example.com/.bundle/hello_world_bundle/dev
Resources:
  Apps:
    hello_world_app:
      Name: hello-world-app
      URL:  https://myworkspace.cloud.databricks.com/apps/hello-world-app?o=8498204313176880

Develop, test, iterate

Continue to make changes to your app locally, then redeploy the bundle to update the app in the workspace. To start the app in the workspace, run the app in the bundle by specifying the resource key for the app in the command:

Bash
databricks bundle run hello_world_app

Deploy to production

Databricks recommends using a service principal for authentication in production. When you are ready to make the app available in production, update your bundle configuration to use a service principal, then deploy the bundle to your target production workspace. For information about service principals, see Service principals for CI/CD.

Modify bundle to use a service principal

Before deploying to production, configure a grant in the bundle that gives permission to a service principal. You can configure the grant when the app is created or when the bundle is run.

To grant the service principal permission when the app is created on bundle deploy, modify the bundle's databricks.yml to define a grant for the app. Use a bundle substitution to assign the service principal:

YAML
bundle:
  name: hello_world_bundle

resources:
  apps:
    hello_world_app:
      name: 'hello-world-app'
      source_code_path: . # This assumes the app source code is at the root of the project.
      description: 'A Databricks app'

  schemas:
    my_schema:
      name: my_schema
      grants:
        - principal: '${resources.apps.hello_world_app.service_principal_client_id}'
          privileges:
            - CREATE_TABLE
      catalog_name: main

targets:
  dev:
    mode: development
    default: true
    workspace:
      host: https://myworkspace.cloud.databricks.com
  prod:
    mode: production
    workspace:
      host: https://myworkspace.cloud.databricks.com
      root_path: /Workspace/Users/someone@example.com/.bundle/${bundle.name}/${bundle.target}
    permissions:
      - user_name: someone@example.com
        level: CAN_MANAGE

Alternatively, define a job in the bundle that configures a grant when the bundle is run:

Add a notebook called grant_notebook.ipynb with the following contents in a cell. Replace <schema-name> with an admin username.

Python
app_service_principal = dbutils.widgets.get("app_service_principal")
spark.sql(f"GRANT ALL PRIVILEGES ON SCHEMA <schema-name> TO `{app_service_principal}`")

Define a job in the bundle's databricks.yml to run a notebook that grants permission to the service principal. Use bundle substitutions to assign the service principal value:

YAML
bundle:
  name: hello_world_bundle

resources:
  apps:
    hello_world_app:
      name: 'hello-world-app'
      source_code_path: . # This assumes the app source code is at the root of the project.
      description: 'A Databricks app'

  jobs:
    grant_job:
      name: 'grant-job'
      parameters:
        - name: app_service_principal
          default: '${resources.apps.hello_world_app.service_principal_client_id}'
      tasks:
        - task_key: setup_grants
          notebook_task:
            notebook_path: ./grant_notebook.ipynb

targets:
  dev:
    mode: development
    default: true
    workspace:
      host: https://myworkspace.cloud.databricks.com
  prod:
    mode: production
    workspace:
      host: https://myworkspace.cloud.databricks.com
      root_path: /Workspace/Users/someone@example.com/.bundle/${bundle.name}/${bundle.target}
    permissions:
      - user_name: someone@example.com
        level: CAN_MANAGE

Deploy the updated bundle

Now deploy the bundle to the production workspace and run the app:

Bash
databricks bundle deploy -t prod
databricks bundle run grant_job -t prod # (Optional) Run this if the grant is configured with a job
databricks bundle run hello_world_app -t prod

Requirements​

Create an app locally​

Add an existing app to an existing bundle​

Develop and debug the app locally​

Deploy the app to the workspace​

Develop, test, iterate​

Deploy to production​

Modify bundle to use a service principal​

Deploy the updated bundle​

Additional resources​