environments command group

The environments command group within the Databricks CLI allows you to manage environment resources. The Environments API provides management capabilities for different types of environments including workspace-level base environments that define the environment version and dependencies to be used in serverless notebooks and jobs.

databricks environments create-workspace-base-environment

Create a new workspace base environment. This is a long-running operation that asynchronously generates a materialized environment to optimize dependency resolution.

databricks environments create-workspace-base-environment DISPLAY_NAME [flags]

Arguments

DISPLAY_NAME

    Human-readable display name for the workspace base environment.

Options

--base-environment-type BaseEnvironmentType

    The type of base environment (CPU or GPU). Supported values: CPU, GPU

--filepath string

    The workspace files or Unity Catalog volumes path to the environment YAML file.

--json JSON

    The inline JSON string or the @path to the JSON file with the request body.

--name string

    The resource name of the workspace base environment.

--no-wait

    Do not wait to reach DONE state.

--request-id string

    A unique identifier for this request.

--timeout duration

    Maximum amount of time to reach DONE state.

--workspace-base-environment-id string

    The ID to use for the workspace base environment, which will become the final component of the resource name.

Global flags

Examples

The following example creates a CPU workspace base environment:

databricks environments create-workspace-base-environment "My Python Env" --base-environment-type CPU --filepath /Workspace/environments/env.yaml

databricks environments delete-workspace-base-environment

Delete a workspace base environment. Deleting a base environment may impact linked notebooks and jobs. This operation is irreversible.

databricks environments delete-workspace-base-environment NAME [flags]

Arguments

NAME

    Required. The resource name of the workspace base environment to delete. Format: workspace-base-environments/{workspace_base_environment}.

Options

Global flags

Examples

The following example deletes a workspace base environment:

databricks environments delete-workspace-base-environment workspace-base-environments/my-env-id

databricks environments get-default-workspace-base-environment

Get the default workspace base environment configuration. Returns the current default base environment settings for both CPU and GPU compute.

databricks environments get-default-workspace-base-environment NAME [flags]

Arguments

NAME

    A static resource name of the default workspace base environment. Format: default-workspace-base-environment.

Options

Global flags

Examples

The following example gets the default workspace base environment:

databricks environments get-default-workspace-base-environment default-workspace-base-environment

databricks environments get-operation

Get the status of a long-running operation. Clients can use this method to poll the operation result.

databricks environments get-operation NAME [flags]

Arguments

NAME

    The name of the operation resource.

Options

Global flags

Examples

The following example gets the status of a long-running operation:

databricks environments get-operation operations/1234567890

databricks environments get-workspace-base-environment

Get a workspace base environment by its name.

databricks environments get-workspace-base-environment NAME [flags]

Arguments

NAME

    Required. The resource name of the workspace base environment to retrieve. Format: workspace-base-environments/{workspace_base_environment}.

Options

Global flags

Examples

The following example gets a workspace base environment:

databricks environments get-workspace-base-environment workspace-base-environments/my-env-id

databricks environments list-workspace-base-environments

List all workspace base environments in the workspace.

databricks environments list-workspace-base-environments [flags]

Arguments

None

Options

--page-size int

    The maximum number of environments to return per page.

--page-token string

    Page token for pagination.

Global flags

Examples

The following example lists all workspace base environments:

databricks environments list-workspace-base-environments

databricks environments refresh-workspace-base-environment

Refresh the materialized environment for a workspace base environment. This is a long-running operation that asynchronously regenerates the materialized environment. The existing materialized environment remains available until it expires.

databricks environments refresh-workspace-base-environment NAME [flags]

Arguments

NAME

    Required. The resource name of the workspace base environment to refresh. Format: workspace-base-environments/{workspace_base_environment}.

Options

--no-wait

    Do not wait to reach DONE state.

--timeout duration

    Maximum amount of time to reach DONE state.

Global flags

Examples

The following example refreshes a workspace base environment:

databricks environments refresh-workspace-base-environment workspace-base-environments/my-env-id

databricks environments setup-local

Set up a local Python environment that matches a Azure Databricks cluster or serverless version, so code you run on your machine behaves the same as it does on Azure Databricks. This installs the matching Python version and a compatible databricks-connect, and pins your dependencies to versions known to work with your chosen compute. It creates or updates a .venv (managed by uv) in the current directory and records the setup in pyproject.toml. The rest of your project stays unchanged.

databricks environments setup-local [flags]

Arguments

None

Options

--cluster-id string

    Cluster ID to use as the compute target.

--cluster-name string

    Cluster name to use as the compute target (resolved to an ID through the Clusters API).

--serverless-version string

    Serverless version to use as the compute target (for example, 5).

--job-task string

    Job task to use as the compute target, in the form <job-id>.<task-key>. The task key is required.

--constraints-only

    Apply the Python version and dependency constraints without adding databricks-connect.

--dry-run

    Compute the plan and show what would change without writing any files or provisioning.

Global flags

Examples

Match a serverless version:

databricks environments setup-local --serverless-version 5

Match an existing cluster by name:

databricks environments setup-local --cluster-name my-cluster

See what would change without writing anything:

databricks environments setup-local --serverless-version 5 --dry-run

databricks environments update-default-workspace-base-environment

Update the default workspace base environment configuration. Sets the specified base environments as the workspace defaults for CPU and/or GPU compute.

databricks environments update-default-workspace-base-environment NAME UPDATE_MASK [flags]

Arguments

NAME

    The resource name of this singleton resource. Format: default-workspace-base-environment.

UPDATE_MASK

    Field mask specifying which fields to update. Valid field paths: cpu_workspace_base_environment, gpu_workspace_base_environment. Use * to update all fields.

Options

--cpu-workspace-base-environment string

    The default workspace base environment for CPU compute.

--gpu-workspace-base-environment string

    The default workspace base environment for GPU compute.

--json JSON

    The inline JSON string or the @path to the JSON file with the request body.

--name string

    The resource name of this singleton resource.

Global flags

Examples

The following example sets the default CPU workspace base environment:

databricks environments update-default-workspace-base-environment default-workspace-base-environment cpu_workspace_base_environment --cpu-workspace-base-environment workspace-base-environments/my-cpu-env

databricks environments update-workspace-base-environment

Update an existing workspace base environment. This is a long-running operation that asynchronously regenerates the materialized environment. The existing materialized environment remains available until it expires.

databricks environments update-workspace-base-environment NAME DISPLAY_NAME [flags]

Arguments

NAME

    The resource name of the workspace base environment. Format: workspace-base-environments/{workspace_base_environment}.

DISPLAY_NAME

    Human-readable display name for the workspace base environment.

Options

--base-environment-type BaseEnvironmentType

    The type of base environment (CPU or GPU). Supported values: CPU, GPU

--filepath string

    The workspace files or Unity Catalog Volumes path to the environment YAML file.

--json JSON

    The inline JSON string or the @path to the JSON file with the request body.

--name string

    The resource name of the workspace base environment.

--no-wait

    Do not wait to reach DONE state.

--timeout duration

    Maximum amount of time to reach DONE state.

Global flags

Examples

The following example updates a workspace base environment:

databricks environments update-workspace-base-environment workspace-base-environments/my-env-id "Updated Python Env" --filepath /Workspace/environments/updated-env.yaml

Global flags

--debug

  Whether to enable debug logging.

-h or --help

    Display help for the Databricks CLI or the related command group or the related command.

--log-file string

    A string representing the file to write output logs to. If this flag is not specified then the default is to write output logs to stderr.

--log-format format

    The log format type, text or json. The default value is text.

--log-level string

    A string representing the log format level. If not specified then the log format level is disabled.

-o, --output type

    The command output type, text or json. The default value is text.

-p, --profile string

    The name of the profile in the ~/.databrickscfg file to use to run the command. If this flag is not specified then if it exists, the profile named DEFAULT is used.

--progress-format format

    The format to display progress logs: default, append, inplace, or json

-t, --target string

    If applicable, the bundle target to use