Skip to main content

Databricks configuration profiles

A Databricks configuration profile stores authentication settings in the .databrickscfg file. Configuration profiles make it easy to switch between different workspaces, environments, or authentication methods without changing your code.

Tools, SDKs, scripts, and apps can reference configuration profiles to authenticate with Databricks. All tools and SDKs that implement unified authentication support configuration profiles.

What is a configuration profile?​

A configuration profile is a named section in the .databrickscfg file that contains the following:

  • Authentication credentials, such as tokens or service principal credentials
  • The Databricks workspace or account URL
  • Optional settings specific to your authentication method

Create multiple profiles in a single .databrickscfg file to manage connections to different workspaces or environments like development, staging, and production.

Create a configuration profile​

Create a configuration profile using the Databricks CLI or by manually editing the .databrickscfg file.

Create a profile with the CLI​

The easiest way to create a configuration profile for interactive user authentication is with the Databricks CLI:

Bash
databricks auth login --host <workspace-url>

The CLI opens your web browser to complete the authentication flow. After you sign in, the CLI saves the credentials as a configuration profile.

Create a profile manually​

To create a configuration profile manually:

  1. Create a file named .databrickscfg in your home directory:

    • Unix, Linux, macOS: ~/.databrickscfg
    • Windows: %USERPROFILE%\.databrickscfg

  2. Add a profile with the following format:

    [<profile-name>]
    <field-name> = <field-value>

    Replace the placeholders:

    • <profile-name>: A unique name like DEFAULT, DEVELOPMENT, or PRODUCTION
    • <field-name> and <field-value>: The authentication fields for your authentication method

For example, for OAuth machine-to-machine (M2M) authentication, the .databrickscfg file looks like this:

[DEFAULT]
host                   = https://<workspace-url>
google_service_account = <service-account-email>

Create multiple profiles​

Define multiple profiles in the same .databrickscfg file to manage different workspaces or environments. Each profile must have a unique name.

[DEFAULT]
host                   = https://production-workspace-url
google_service_account = <production-service-account>

[DEVELOPMENT]
host                   = https://dev-workspace-url
google_service_account = <dev-service-account>

Combine authentication types​

Define multiple authentication methods in separate profiles within your configuration file. This is useful when you want to use different credentials for different workflows or tools. For example, you might use cloud-native authentication for interactive use and OAuth credentials for automation:

[DEFAULT]
host = https://<workspace-url>

[SERVICE_ACCOUNT]
host                   = https://<workspace-url>
google_service_account = <service-account-email>

For more information about authentication types and their required fields, see Databricks unified authentication.

Use a configuration profile​

After you create a configuration profile, reference it in your tools and code. If you don't specify a profile name, Databricks tools and SDKs automatically use the DEFAULT profile.

To use a profile other than DEFAULT, specify the profile name:

With the Databricks CLI:

Bash
databricks workspace list --profile DEVELOPMENT

With environment variable:

Bash
export DATABRICKS_CONFIG_PROFILE=DEVELOPMENT
databricks workspace list

With the Python SDK:

Python
from databricks.sdk import WorkspaceClient

# Specify profile in code
w = WorkspaceClient(profile="DEVELOPMENT")

# Or use environment variable DATABRICKS_CONFIG_PROFILE

Best practices​

  • Use the DEFAULT profile for your most common workspace to minimize the need to specify profile names.
  • Use descriptive profile names like PRODUCTION, DEVELOPMENT, or STAGING instead of generic names.
  • Protect your .databrickscfg file by setting restricted file permissions (readable only by your user).
  • Don't commit .databrickscfg to version control. Add it to your .gitignore file.
  • Use service principals for production workloads instead of personal access tokens.
  • Rotate credentials regularly and update your profiles accordingly.

Troubleshooting​

If the profile can't be found, verify the following:

  • The .databrickscfg file is in your home directory.
  • You use the exact profile name.
  • The file isn't named .databrickscfg.txt or something similar.

If authentication fails, verify the following:

  • Your credentials are current and haven't expired.
  • The host URL is correct.
  • You have the required permissions for the operations that you're attempting.

Test your configuration profiles using the Databricks CLI:

Bash
# Inspect a specific profile
databricks auth env --profile DEVELOPMENT

# List all profiles
databricks auth profiles

For more information, see Test your configuration profiles.

Learn more​

Last updated on