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.
To initialize an example bundle with a Streamlit app, use the streamlit-app bundle template with the bundle init
command:
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:
-
Follow a quick start tutorial for a framework:
-
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:
YAMLcommand: ['streamlit', 'run', 'app.py']
Or for a Dash app:
YAMLcommand: ['python', 'app.py']
-
-
To create an app in the workspace and sync it locally:
-
Follow the steps in Create a custom Databricks app to create an app in the UI.
-
Create a local directory for the app and
cd
into it:Bashmkdir hello-world-app
cd hello-world-app -
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:Bashdatabricks 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:
-
Clone the Databricks app templates GitHub repository:
Bashgit clone https://github.com/databricks/app-templates
-
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:
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 and prepare the virtual environment, then start the app and debugger, use the
run-local
command with the--prepare-environment
and--debug
options:Bashdatabricks apps run-local --prepare-environment --debug
This command uses
uv
to prepare the virtual environment and the debugger is based ondebugpy
. -
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 using bundles
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 adatabricks.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:YAMLbundle:
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.Bashdatabricks bundle validate
Bashdatabricks bundle deploy
-
Use the
bundle summary
command to retrieve the app resource URL to open the app page in the workspace:Bashdatabricks bundle summary
OutputName: 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, then deploy to production
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:
databricks bundle run hello_world_app
When you are ready to make the app available in production, deploy the bundle to your target production workspace and run the app:
databricks bundle deploy -t prod
databricks bundle run hello_world_app -t prod