Skip to main content
Last updated on

Set up the Databricks Excel Add-in

The Databricks Excel Add-in connects your Databricks workspace to Microsoft Excel, bringing governed Lakehouse data directly into your spreadsheets. The add-in is fully supported across Excel for the web and desktop versions for both Windows and macOS.

This page describes the two methods available to set up the Databricks Excel Add-in in Microsoft Excel. This add-in uses single sign-on (SSO) authentication to connect to your Databricks workspace and supports Unity Catalog for data governance and access control.

Prerequisites​

Before you install the Excel Add-in, verify that you have the following:

  • Access to a Databricks workspace with Unity Catalog enabled.
  • Ensure a workspace admin has enabled the Excel Connector preview. See Manage Databricks previews.
  • Your Databricks workspace URL for each workspace that Excel should connect to.
  • You have Databricks SQL access and at least CAN USE permission on a SQL warehouse. To import data with low latency, you can also use a Lakehouse//RT warehouse, which supports imports only.
  • Permissions to read data from Unity Catalog tables in your workspace.
  • One of the following versions of Excel:
    • Excel 2019 or later on Mac
    • Excel on Windows (Microsoft 365)
    • Excel on the web
    • Excel on Mac (Microsoft 365)
  • If you use a firewall or a cloud security platform, allowlist the Databricks workspace URLs included in the add-in file.
  • If your Microsoft Entra tenant blocks user consent for third-party apps, a Microsoft Entra admin must grant admin consent to the Databricks single sign-on enterprise application before users can sign in with the account picker. This is not required if users sign in by entering a workspace URL directly. See "Need admin approval" message on log in.

Set up the add-in file​

note

If you are an admin deploying the add-in through the Microsoft Marketplace, skip this section. The marketplace deployment uses PowerShell to configure workspace access instead of the add-in file. See Deploy through Microsoft Marketplace.

The add-in file is a small connector file that tells Excel how to securely connect to Databricks. It acts as the digital handshake that ensures the add-in loads correctly and stays up to date every time you open Excel.

Download and set up the add-in file to use the Databricks Excel Add-in. A single add-in file can connect to multiple Databricks workspaces.

  1. Download the Databricks Excel add-in file:

    Download the Excel add-in file

  2. Edit the add-in file by specifying your workspace URL as an <AppDomain> within the AppDomains section. Your workspace URL is the base URL you use to access your Databricks workspace in a browser. To switch between multiple Databricks workspaces, add each workspace URL to the add-in file.

    To sign in with a custom URL, add both the custom URL and the associated workspace URL as separate <AppDomain> entries, as shown in the following examples. Sign-in can redirect to either URL.

    XML
    <AppDomains>
       <!-- DO NOT CHANGE -->
       <AppDomain>https://www.databricks.com</AppDomain>
       <AppDomain>https://login.databricks.com</AppDomain>
       <!-- ADD WORKSPACE URLS AS SHOWN BELOW; PUT EACH WORKSPACE URL IN ITS OWN <AppDomain> TAG  -->
       <!-- EXAMPLE -->
       <AppDomain>https://<workspace1-id>.cloud.databricks.com</AppDomain>
       <AppDomain>https://<workspace2-id>.cloud.databricks.com</AppDomain>
       <!-- TO USE A CUSTOM URL, ADD BOTH THE CUSTOM URL AND ITS ASSOCIATED WORKSPACE URL -->
       <AppDomain>https://<custom-url>.databricks.com</AppDomain>
    </AppDomains>
    note

    Paste your workspace URL as plain text, without formatting. In most text editors, use Ctrl+Shift+V (Windows) or Command+Shift+V (macOS).

  3. Save your changes. Verify that the file is properly formatted as an .xml file.

Option 1: Deploy from Microsoft 365 admin center​

As a global administrator, you can deploy the Databricks Excel Add-in to users in your organization. You can deploy the add-in as a custom app using the add-in file or install it from the Microsoft Marketplace.

To install the Databricks Excel Add-in as a Microsoft 365 Admin, you must have the global admin permission. As an administrator, you can determine which users in your organization can use add-ins. For more about global admins on Microsoft 365, see the Microsoft documentation.

Access the Microsoft 365 admin center here.

note

Databricks recommends deploying the Databricks Excel Add-in as a custom app.

Deploy as a custom app​

Deploy the add-in using a custom manifest file. Download and set up the add-in file provided in the Prerequisites.

  1. In the Microsoft 365 admin center, go to Settings > Integrated apps and click the Add-ins link.
  2. Click Deploy Add-in and click Next.
  3. Click Upload custom apps as the option to deploy a new add-in.
  4. Select the option to upload a manifest. Click Choose File and upload the add-in file.
  5. Choose which users should have access to the add-in.
  6. Click Deploy.

For detailed steps about uploading the Databricks Excel Add-in, see the Microsoft documentation.

Deploy from Microsoft Marketplace​

Install the add-in from the Microsoft Marketplace and use PowerShell to configure workspace access. Installing the add-in alone doesn't connect it to your Databricks workspaces. Follow all the steps below, including allowlisting your workspace URLs with PowerShell.

Prerequisites​

  • PowerShell is installed on your machine.
  • You must run Windows PowerShell as an administrator.

Install the add-in​

  1. In the Microsoft 365 admin center, go to Settings > Integrated apps and click the Get Apps link.
  2. Search for "Databricks Add-in for Excel".
  3. Click Get it now.
  4. Deploy the add-in to yourself by selecting Just me under Assign Users.
  5. Click Deploy.

For detailed steps about deploying the Databricks Excel Add-in from the Microsoft Marketplace, see the Microsoft documentation.

Configure workspace access​

After installing the add-in, use PowerShell to allowlist your Databricks workspace URLs.

note

The PowerShell connection to the Office 365 admin center can time out. If a command fails, reopen PowerShell and reconnect by running Connect-OrganizationAddInService.

  1. Open PowerShell and run as an administrator. For more information, see the Microsoft documentation.

  2. Install and import the Office 365 centralized deployment module:

    PowerShell
    Install-Module -Name O365CentralizedAddInDeployment
    Import-Module O365CentralizedAddInDeployment

  3. Connect and log in to your Office 365 tenant as an admin:

    PowerShell
    Connect-OrganizationAddInService

  4. Confirm that the add-in was deployed. The Databricks Add-in for Excel should appear in the list.

    PowerShell
    Get-OrganizationAddIn

    If the add-in does not appear, it might need to be redeployed or might still be deploying.

  5. Allowlist Databricks workspace URLs. Replace each <workspace-url> with the URL of a workspace you want to allow. You can include as many workspace URLs as you need. To support a custom URL, include both the custom URL and the associated workspace URL.

    PowerShell
    Set-OrganizationAddInOverrides -ProductId 305c35cc-5f58-46b6-8701-d611c3379a86 `
      -AppDomains "https://<workspace1-url>", "https://<workspace2-url>", "https://<custom-url>.databricks.com"

    The product ID for Databricks is 305c35cc-5f58-46b6-8701-d611c3379a86.

    The command might return There was an error uploading the Add-In even when the workspace URLs are allowlisted successfully. Before you run the command again, complete the next step to check whether the allowlisting was applied.

  6. Confirm correct allowlisting. The workspace URLs you allowlisted should appear in the AppDomains section.

    PowerShell
    Get-OrganizationAddInOverrides -ProductId 305c35cc-5f58-46b6-8701-d611c3379a86

Test the add-in​

  1. In Excel, find the Databricks Add-in.
  2. Sign in and connect to one of the workspaces you allowlisted.
note

Allowlisting changes can take some time to sync. If authentication fails, confirm that you are connecting to an allowlisted workspace. If the workspace is correct, close Excel and try again later.

Deploy to your organization​

  1. In the Microsoft 365 admin center, go to Settings > Integrated apps.
  2. Select the Databricks Add-in that you installed and configured.
  3. Click the Users tab and choose whether to deploy to your entire organization or a specific group of users.
note

As an administrator, share the account name associated with the workspaces that you allowlisted with the users who plan to use the Databricks Excel Add-in. See Sign in to the add-in.

Option 2: Deploy as an individual user​

Installation steps vary depending on your Excel platform. Download and set up the add-in file provided in the Prerequisites.

To install and connect to the Excel Add-in in Excel for the web do the following:

  1. Open Excel for the web and create or open a workbook.
  2. Under the Home tab, click Add-ins > Advanced.
  3. Click Upload My Add-in.
  4. Upload the add-in file.
  5. Click Upload.
  6. Find and click the Databricks Add-in from the Add-ins menu.
  7. Sign in to your Databricks account. If there is an error, make sure to enable pop-up dialogs.
  8. If you configured multiple workspace URLs, select the desired Databricks account name. You only need to select a specific workspace if the URLs are within the same account. For more information on account names, see Locate your account ID.

Sign in to the add-in​

If an administrator in your organization has deployed the Databricks Excel Add-in, sign in and connect to your Databricks workspace from Excel.

  1. In Excel, under the Home tab, click the Databricks Add-in.

  2. The first time you sign in, connect to a workspace using one of the following options:

    • Enter a workspace URL (recommended): Enter your Databricks workspace URL. This option signs you in with workspace SSO. To sign in with a custom URL, verify that both the custom URL and the associated workspace URL are added to the add-in file. See Set up the add-in file.

    • Use the account picker: Click Select account picker to open login.databricks.com, and then select an allowlisted account and workspace.

      note

      The account picker is not available on GovCloud. Use a workspace URL to sign in.

  3. Click Sign in and complete the authentication process to gain access to the Databricks Excel Add-in.

After your first sign-in, the add-in remembers your workspaces. On later sign-ins, select a workspace from the drop-down menu, or use either option above to connect to a different workspace.

If you use Microsoft Entra ID authentication and the "Need admin approval" message appears, a Microsoft Entra admin must approve the Databricks enterprise application before you can sign in. See "Need admin approval" message on log in.

Change Databricks workspace​

If your add-in file specifies multiple Databricks workspaces, you can switch between those workspaces. For more information, see Set up the add-in file.

To connect to a different Databricks workspace, do the following:

  1. In the upper-right of the Databricks Add-in pane, click the three-dot menu next to the compute selector.
  2. Click Change workspace.
  3. Select the account your workspace is in, the workspace if prompted, and sign in.

Troubleshooting​

"Authentication in progress" message on log in​

If you see an "Authentication in progress" window when trying to log in to Databricks from the add-in, your workspace might not have been correctly added to the custom add-in file. Verify that you have configured your workspace correctly under <AppDomains>.

"Need admin approval" message on log in​

The following "Need admin approval" message appears when you log in to your Databricks workspace from the Excel add-in because the Microsoft Entra tenant is blocking user consent for the Databricks application. This applies only when you sign in with the account picker (login.databricks.com); to avoid it, enter your workspace URL directly when you sign in. If administrator consent is not granted, Microsoft Entra ID continues to block the login flow even if you have direct workspace access.

note

This issue affects the Excel desktop app on the June 2026 release.

Need admin approval message in the Excel add-in

To resolve this, a Microsoft Entra user with appropriate administrator roles must grant tenant-wide administrator consent to the Databricks enterprise application.

Ask the Microsoft Entra admin to visit the following link. Replace {TENANT_ID} with your Microsoft Entra tenant ID:

Text
https://login.microsoftonline.com/{TENANT_ID}/adminconsent?client_id=aaec40b0-c0ae-4211-a98b-6fc160abb71b

If the link fails, the admin can grant consent manually:

  1. In the Microsoft Entra admin center, go to Entra ID > Enterprise apps > All applications and find the Databricks enterprise application used for single sign-on. To identify the application, search for the Application ID aaec40b0-c0ae-4211-a98b-6fc160abb71b.
  2. Grant admin consent for the permissions requested by the Databricks enterprise app:
    1. Under Security, click Permissions.
    2. Click Grant admin consent.

For detailed instructions, see the Microsoft documentation.

Add-in error​

You might see the following error when authenticating to your workspace:

Text
ADD-IN ERROR

This add-in could not be started. Close this dialog to ignore the problem or click "Restart" to try again.

This is a known Microsoft Edge WebView2 issue (office-js #6771) that blocked the add-in's sign-in redirect on Excel for Windows desktop. Update Microsoft Edge to the latest stable version to resolve it.

Unable to use resources​

If you're unable to use Databricks resources, such as SQL warehouses, in the Databricks Add-in, try one of the following methods depending on which version of Excel you're using:

  • Excel for the web: Restart the sheet or change workspaces and log back in to the same workspace. See Change Databricks workspace.
  • Excel Desktop: Reload the add-in by clicking the information icon in the upper-right corner and selecting Reload.

Next steps​

On this page