DataBricks CLI eXtensions (dbx)

0.8.19 · active · verified Thu Apr 16

dbx is a Python CLI extension for Databricks that simplifies project development, deployment, and management workflows, especially for MLOps. It provides tools for structuring Databricks projects, building artifacts, and deploying them to various Databricks environments. The current version is 0.8.19, and it maintains an active release cadence with frequent updates.

Common errors

```
Error: "No profiles found. Run 'dbx configure' in your terminal."
```
cause dbx has not been configured with Databricks credentials or host information, or the specified profile does not exist.

fix Run `dbx configure` in your terminal to set up a default profile, or set `DBX_HOST` and `DBX_TOKEN` environment variables before running dbx commands. If using a specific profile, ensure it's selected or specified.
```
FileNotFoundError: [Errno 2] No such file or directory: 'dbx.json'
```
cause dbx could not find the project configuration file (`dbx.json`) in the current working directory.

fix Ensure that `dbx.json` is present in your current working directory. If your project file is elsewhere, you might need to change your directory or specify the path to `dbx.json`.
```
Error: Invalid configuration for target 'dev': 'workspace_path' is required
```
cause The deployment target (e.g., 'dev') in your `deployment.yml` file is missing the mandatory `workspace_path` property.

fix Edit your `deployment.yml` file and add a `workspace_path` entry under the specific target configuration, e.g., `targets: dev: workspace_path: /Shared/dbx/my_project_name`.
```
Error: "click.exceptions.BadParameter: Error: Unknown command 'deploy'"
```
cause The dbx CLI command or subcommand is misspelled, or it's not available in the currently installed dbx version, or dbx is not correctly installed/accessible in the PATH.

fix Verify the command syntax against the official dbx documentation. Ensure `dbx` is properly installed and its executable is in your system's PATH. Reinstall `dbx` if necessary: `pip install --upgrade dbx`.

Warnings

breaking Project configuration format changed from `dbx_project.py` (Python object) to `dbx.json` (JSON file) starting with dbx v0.8.0. Old projects will not be recognized without migration.
Fix: Migrate your project configuration from `dbx_project.py` to the new `dbx.json` format. Refer to the official dbx migration guide for detailed steps.
gotcha dbx relies on correctly configured Databricks credentials and host information. This can be managed via `dbx configure` (which stores profiles locally) or by setting `DBX_HOST` and `DBX_TOKEN` environment variables.
Fix: Ensure you have run `dbx configure` to set up a profile, or explicitly set `DBX_HOST` and `DBX_TOKEN` environment variables for your session. Use `dbx configure --profile <profile_name>` to manage multiple profiles.
gotcha When deploying, it's common to misconfigure the `workspace_path` or `target` in `deployment.yml`, leading to resources being deployed to unintended locations or errors.
Fix: Always double-check your `deployment.yml` to ensure the `workspace_path` and `target` definitions (e.g., `dev`, `staging`, `prod`) correctly point to your desired Databricks workspace locations and clusters.

Install

pip install dbx Install dbx

Imports

dbx_api
```
from dbx.api import dbx_api
```
Provides programmatic access to dbx project operations like building, deploying, and managing profiles. Assumes prior CLI configuration.

Quickstart

Demonstrates programmatic access to `dbx` for retrieving project configuration and listing profiles. This requires an existing `dbx` project setup with `dbx.json` and `deployment.yml` files, and configured Databricks credentials (e.g., via `dbx configure` or environment variables).

import os
from dbx.api import dbx_api

# This example assumes you have a 'dbx.json' and 'deployment.yml'
# in your current working directory, defining a dbx project.
# It also assumes you have configured dbx credentials (e.g., via `dbx configure`)
# or set environment variables like DBX_HOST and DBX_TOKEN.

print("Attempting to get project configuration...")
try:
    # Load the project configuration from dbx.json in the current directory
    project_config = dbx_api.get_project_config()
    print(f"Project Name: {project_config.project_name}")
    print(f"Project Type: {project_config.project_type}")

    # A simpler example: listing current connection profiles
    print("\nListing configured dbx connection profiles:")
    profiles = dbx_api.get_available_profiles()
    if profiles:
        for profile in profiles:
            print(f"- {profile}")
    else:
        print("No profiles found. Run `dbx configure` to set one up.")

except Exception as e:
    print(f"Error interacting with dbx API. Ensure dbx is configured and project files exist. Error: {e}")
    print("Hint: Run `dbx configure` in your terminal to set up credentials.")

view raw JSON →