Skip to main content

Installation

Lakebridge can be installed in two ways. Pick the path that fits your environment:

  • Desktop App — a graphical installer for macOS and Windows. Best if you prefer a UI and want the fewest manual steps: it bundles the Databricks CLI and Python and installs Lakebridge for you. Available from release v0.14.0 onwards.
  • Command-line (CLI) — install via the Databricks CLI. Best for automation, headless or server environments, Linux, or if you already work in the terminal.

Both paths connect to a Databricks workspace, require Java 21 or above (for the Morpheus transpiler), and need network access to GitHub, Maven Central, and PyPI. Each flow below is self-contained — follow the one you chose.

Desktop App​

The desktop app is a graphical installer for macOS and Windows. The installer is published as an asset on each GitHub release, from v0.14.0 onwards.

note

The desktop app has its own version line (e.g. 1.3.2), which is independent of the Lakebridge release tag it ships with — so the version in the installer filename does not match the release version.

Requirements​

RequirementDetails
Databricks workspaceAny workspace (production, development, or free trial)
JavaJava 21 or above (required for the Morpheus transpiler) — download
Network accessGitHub, Maven Central, PyPI (see Network access)
note

Unlike the CLI installation, you do not need to pre-install the Databricks CLI, Python, or Lakebridge itself — the app bundles the Databricks CLI and Python, and installs Lakebridge for you on first run.

Download​

Grab the installer for your platform from the latest release. Choose the build that matches your operating system and CPU architecture:

PlatformApple Silicon / ARMIntel / AMD (x64)
macOSMacOS-Lakebridge-<app-version>-arm64.dmgMacOS-Lakebridge-<app-version>-x64.dmg
WindowsWindows-Lakebridge-<app-version>-arm64.exeWindows-Lakebridge-<app-version>-x64.exe
Which architecture?
  • macOS: Apple Silicon (M1/M2/M3/M4) uses arm64; older Intel Macs use x64.
  • Windows: most machines use x64; use arm64 only for ARM-based devices (e.g. Surface Pro X).

Install​

  1. Download the .dmg matching your Mac's architecture.
  2. Open the .dmg and drag Lakebridge into your Applications folder.
  3. Launch Lakebridge from Applications.

First run​

On first launch, the app walks you through everything needed to get started:

  1. Check prerequisites — the app verifies Java is installed at a supported version. If it is missing, install Java 21 or above and re-check.
  2. Connect to Databricks — enter your workspace URL and sign in. The app authenticates via OAuth in your browser and configures the Databricks CLI profile for you.
  3. Install Lakebridge — the app installs the Lakebridge CLI (and its bundled Databricks CLI and Python) in the background.

Once these steps complete, you can run assessment, transpilation, and profiling directly from the app.

Installing Lakebridge using the desktop app

Command-line (CLI)​

Prerequisites​

RequirementDetails
Databricks workspaceAny workspace (production, development, or free trial)
Databricks CLIInstall here and configure with PAT or Service Principal
Python3.10.1–3.14.x
JavaJava 21 or above (required for the Morpheus transpiler)
Network accessGitHub, Maven Central, PyPI (see Network access)

Python and Java​

If necessary:

  • Python can be obtained here; if installing on Windows, please ensure you install the 64-bit version.
  • Java can be obtained here; the current LTS release is recommended.

To verify these are installed and available, from the terminal the following should work and display the installed versions:

python -V
java -version

Configure the Databricks CLI​

Install and authenticate the CLI:

brew tap databricks/tap
brew install databricks

Authenticate the CLI:

databricks configure

Verify connectivity: databricks clusters list

Install Lakebridge​

databricks labs install lakebridge

To use a specific profile:

databricks labs install lakebridge --profile <profile_name>
lakebridge-install

Verify:

databricks labs lakebridge --help

Install Transpile​

databricks labs lakebridge install-transpile

The command will prompt for your source dialect, input/output paths, and target technology.

To install Switch (the LLM transpiler):

databricks labs lakebridge install-transpile --include-llm-transpiler true
Override the default BladeBridge config

During install-transpile you can supply a custom config file for BladeBridge:

Specify the config file to override the default[Bladebridge] config: <path>/custom_config.json

Verify:

databricks labs lakebridge transpile --help

Configure Reconcile​

databricks labs lakebridge configure-reconcile

The command will prompt for your source connection and Databricks catalog to reconcile, and install Lakebridge and create the required workspace resources to run Reconcile. Optionally, the command can discover the tables in your source and generate a base config to run reconcile. This autoconfiguration should be reviewed before running reconcile.

If you don't have permission to create SQL warehouses or clusters, add a warehouse_id or a cluster_id to your Databricks CLI profile:

[profile-name]
host         = <your-workspace-url>
warehouse_id = <your-warehouse-id>
cluster_id = <your-cluster-id>

Verify:

databricks labs lakebridge reconcile --help

Service Principal Setup (Optional)​

For automated/production deployments, use a Service Principal instead of a Personal Access Token. See the Databricks CLI authentication docs for setup instructions.

Network access, proxies, and mirrors​

Both installation paths need access to the following network resources to download Lakebridge and its transpiler plugins:

SiteHostsPurpose
GitHubgithub.com
raw.githubusercontent.com		Packages and metadata used for general installation and upgrades of Lakebridge.
Maven Centralrepo1.maven.orgInstalling and upgrading transpiler plugins.
PyPIpypi.org
files.pythonhosted.org

Support for proxies or mirrors to access these Internet resources can be configured as shown below.

General HTTP proxy configuration​

To configure general HTTP proxy for network access, set an environment variable named https_proxy to the URL of the HTTPS proxy.

export https_proxy=http://my-proxy.example.com:3128/

Contact your IT team if necessary for information on the URL to use. If authentication is needed, refer to the section below.

Maven Central​

If a local mirror should be used for downloading resources from Maven Central, set the LAKEBRIDGE_MAVEN_URL environment to the URL of the mirror.

export LAKEBRIDGE_MAVEN_URL=https://mirror.example.com/maven/releases/

Contact your IT team if necessary for information on the URL to use. If authentication is needed, refer to the section below.

PyPI​

If a local mirror should be used for downloaded resources from PyPI, this needs to be configured with pip:

pip3 config --user set global.index-url https://mirror.example.com/pypi

Contact your IT team if necessary for information on the URL to use. If authentication is needed, refer to the section below.

Proxy or Mirror Authentication​

If authentication is needed to access a mirror or proxy, a ~/.netrc file can be used to specify the credentials to use. The format is of the form:

machine my-proxy.example.com
login bobby
password tAble5

Note that my-proxy.example.com should be the host from the URL (and not the entire URL).