Skip to main content

AI Runtime quickstart

Databricks recommends starting with the Databricks CLI to run your first AI Runtime workload. The Databricks CLI lets you submit, monitor, and manage serverless GPU workloads from your terminal. If you prefer notebooks, see AI Runtime Notebook quickstart.

Requirements​

  • A Databricks workspace with AI Runtime enabled. See Requirements.
  • Databricks CLI version 1.24.0 or above. Earlier versions lack the databricks air commands, the code_source format, or the accelerator type listing that this quickstart uses.
  • Git installed and available on your PATH to run the Python example. The CLI uses Git to package local code.

Run your first workload​

  1. Install or update the Databricks CLI, and authenticate it to your workspace. See Install or update the Databricks CLI and Authentication for the Databricks CLI.

    tip

    To select a workspace for the walkthrough without repeating --profile, list your profiles and set a default:

    Bash
    databricks auth profiles
    databricks auth switch --profile <profile>
    databricks auth describe

    Check that Host in the output is the workspace where you want to run the workload. For a shell-session default, use export DATABRICKS_CONFIG_PROFILE=<profile> instead. This environment variable takes precedence over the default set by auth switch.

    To override either default for one command, append --profile <other-profile>. Use the same profile for submission, status, and logs: Job Run IDs belong to the workspace where you submitted the workload. See Configuration profiles for the Databricks CLI.

    Confirm that the CLI version is 1.24.0 or above and that the air commands are available:

    Bash
    databricks --version
    databricks air --help

    If databricks air --help returns unknown command "air" for "databricks", your CLI version is too old. Update the CLI and try again.

  2. Create a minimal workload file. The following workload.yaml requests one A10 GPU and runs nvidia-smi to print the GPU name:

    workload.yaml
    experiment_name: air-quickstart
    compute:
    num_accelerators: 1
    accelerator_type: GPU_1xA10
    command: nvidia-smi --query-gpu=name --format=csv,noheader

    accelerator_type values have the form GPU_<GPUs per node>x<GPU model>, such as GPU_1xA10, GPU_1xH100, or GPU_8xH100. For all values, see Accelerator types. To list the accelerator types available in your workspace, run databricks air run -h config.compute.accelerator_type.

  3. Submit the workload and stream its logs with databricks air run:

    Bash
    databricks air run --file workload.yaml --watch

    The CLI returns the Job Run ID and a link to the run in your workspace. --watch keeps the terminal attached and streams logs until the workload finishes.

    Output
    Submitting experiment: air-quickstart
    Submitted workload with Job Run ID: 783940125630184
    View job run at: https://example.cloud.databricks.com/jobs/runs/783940125630184?o=1234567890123456

    Monitoring run and streaming logs...
    ...
    Environment setup completed at Thu Oct 1 14:23:45 UTC 2026
    NVIDIA A10
tip

To get help writing your workload config and managing runs, install the databricks-ai-runtime skill for your AI agent. See Use agent skills with AI Runtime.

Run your own Python code​

To upload and run local Python code, create an air-quickstart directory with the following files:

air-quickstart/
├── workload.yaml
└── src/
└── main.py
tip

To start from a runnable project instead of creating these files manually, clone the AI Runtime cookbook repository and change to the CLI getting-started directory:

Bash
git clone https://github.com/databricks-solutions/ai-runtime-cookbook.git
cd ai-runtime-cookbook/getting-started/air-cli

The cookbook project keeps main.py in the same directory as workload.yaml and uses root_path: ., so its layout differs from the one shown here.

Use the following minimal Python code to verify that AI Runtime runs the uploaded code on the GPU:

src/main.py
import torch

print("Hello from Python on AI Runtime")
print(f"GPU: {torch.cuda.get_device_name(0)}")

To extend this example, you can replace src/main.py with your own training, batch inference, or other AI application.

Use the following configuration for workload.yaml:

workload.yaml
experiment_name: python-quickstart
environment:
version: databricks_ai_v6
compute:
num_accelerators: 1
accelerator_type: GPU_1xA10
code_source:
root_path: ./src
command: python "$CODE_SOURCE_PATH/main.py"

This configuration uses the following settings and runs src/main.py on one A10 GPU:

  • environment.version selects the Databricks AI environment version 6, which includes PyTorch. This key is optional. If you omit it, the CLI uses its default, a Standard environment that doesn't include PyTorch. To see the default version, run databricks air run -h config.environment.version.
  • root_path: ./src uploads the src directory in the same directory as workload.yaml. At runtime, $CODE_SOURCE_PATH points to the uploaded directory.

With the default output location, databricks air convert-to-dabs needs the code in a subdirectory, as in this layout, when you convert the workload to a bundle.

note

The CLI doesn't upload files that Git ignores, including files ignored by an enclosing repository. If the workload can't find main.py, run git check-ignore -v src to check whether the src directory is ignored. See code_source in the workload YAML reference.

In your own workloads, set environment.version to pin the preinstalled packages that your code depends on. For the values that this key accepts, see environment. For the packages in each environment, see Set up your AI Runtime environment.

To bring your own dependency stack, replace the environment block with Standard environment version 6 and explicit dependencies:

YAML
environment:
version: 6
dependencies:
- torch==2.11.0

CLI workloads install these dependencies on every run. This option adds PyTorch and CUDA wheel download time.

Submit the workload from the directory that contains workload.yaml:

Bash
databricks air run --file workload.yaml --watch

The streamed logs include:

Text
...
Hello from Python on AI Runtime
GPU: NVIDIA A10G

Inspect and manage your run​

Each run has a Job Run ID, which databricks air run prints when you submit the workload.

To submit in the background, omit --watch:

Bash
databricks air run --file workload.yaml

The command returns after submission while the workload continues running. Use the returned Job Run ID and the same workspace profile for the following commands.

To check the run status, configuration, and timing, run:

Bash
databricks air get <job-run-id>

The output includes a link to the Job run and, if available, a link to the MLflow run.

To view the run logs, run:

Bash
databricks air logs <job-run-id>

databricks air logs prints existing workload output and continues streaming while the run is active.

Use the Job run link to inspect execution status, compute, attempts, and driver output. Use the MLflow run link to view persistent logs and any parameters, metrics, and artifacts recorded by the workload.

For longer-running workloads, use the MLflow System metrics tab to inspect automatically collected GPU utilization and memory. To log custom metrics and artifacts or compare runs, see Experiment tracking and observability.

To list runs, including completed runs, run:

Bash
databricks air list --all-status

To cancel an active run, run:

Bash
databricks air cancel <job-run-id>

If a run fails, use its status, logs, and available Job or MLflow links to identify the actionable error. Correct the workload or configuration, then submit it again.

Continue exploring the Databricks CLI​

This quickstart uses a minimal workload configuration. See Workload YAML reference to configure environments, code sources, compute, secrets, retries, and other settings.

If the standard environment does not meet your dependency requirements, use a custom Docker image.

To explore complete training, fine-tuning, batch inference, distributed training, and Ray workloads, clone the AI Runtime Cookbook and run a recipe.

Additional resources​