Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
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 Azure Databricks workspace with AI Runtime enabled. See Requirements.
- Databricks CLI version 1.24.0 or above. Earlier versions lack the
databricks aircommands, thecode_sourceformat, or the accelerator type listing that this quickstart uses. - Git installed and available on your
PATHto run the Python example. The CLI uses Git to package local code.
Run your first workload
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:databricks auth profiles databricks auth switch --profile <profile> databricks auth describeCheck that
Hostin the output is the workspace where you want to run the workload. For a shell-session default, useexport DATABRICKS_CONFIG_PROFILE=<profile>instead. This environment variable takes precedence over the default set byauth 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
aircommands are available:databricks --version databricks air --helpIf
databricks air --helpreturnsunknown command "air" for "databricks", your CLI version is too old. Update the CLI and try again.Create a minimal workload file. The following
workload.yamlrequests one A10 GPU and runsnvidia-smito print the GPU name:experiment_name: air-quickstart compute: num_accelerators: 1 accelerator_type: GPU_1xA10 command: nvidia-smi --query-gpu=name --format=csv,noheaderaccelerator_typevalues have the formGPU_<GPUs per node>x<GPU model>, such asGPU_1xA10,GPU_1xH100, orGPU_8xH100. For all values, see Accelerator types. To list the accelerator types available in your workspace, rundatabricks air run -h config.compute.accelerator_type.Submit the workload and stream its logs with
databricks air run:databricks air run --file workload.yaml --watchThe CLI returns the Job Run ID and a link to the run in your workspace.
--watchkeeps the terminal attached and streams logs until the workload finishes.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:
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:
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:
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.versionselects 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, rundatabricks air run -h config.environment.version.root_path: ./srcuploads thesrcdirectory in the same directory asworkload.yaml. At runtime,$CODE_SOURCE_PATHpoints 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:
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:
databricks air run --file workload.yaml --watch
The streamed logs include:
...
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:
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:
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:
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:
databricks air list --all-status
To cancel an active run, run:
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.