Skip to main content

Installation

GeoBrix offers two execution tiers with different installation paths. See Choosing an Execution Tier for the tradeoffs.

Supported Databricks Runtimes​

GeoBrix supports the following Databricks Runtime releases:

DBRUbuntuSparkPythonScalaJavaGeoBrix
17.324.044.0.03.12.32.13.1617✅ Supported
1824.044.1.03.12.32.13.1621✅ Supported
1924.044.2.03.12.32.13.1821✅ Supported

A single wheel + single JAR runs on 17.3, 18, and 19: Scala 2.13 minor versions are binary-compatible, the JAR is compiled to Java-17 bytecode so it loads on all three JVMs, and Spark is a provided dependency.

GeoBrix Light uses explicit, runtime-pinned extras — there is no bare [light]. On Serverless, use geobrix[light_env6] (environment v6, recommended) or geobrix[light_env5] (environment v5). On classic clusters, use geobrix[light_dbr17], geobrix[light_dbr18], or geobrix[light_dbr19] to match your runtime. See the extras table in the Lightweight tab below.

On Serverless, use geobrix[light_env6]

Environment v6 is recommended for Serverless. Install geobrix[light_env6] and set the environment version to 6 — in the Environment side panel, or environment_version: "6" on a job. For an env 5 Serverless cluster, use geobrix[light_env5] instead.

Force-reload on Serverless without touching dependencies. To swap in fresh wheel bytes during an interactive session, run this in a cell towards the top of your notebook:

%pip install --force-reinstall --no-deps "geobrix[light_env6] @ file:///Volumes/<catalog>/<schema>/<volume>/geobrix/geobrix-<version>-py3-none-any.whl"
%pip install "geobrix[light_env6] @ file:///Volumes/<catalog>/<schema>/<volume>/geobrix/geobrix-<version>-py3-none-any.whl"
dbutils.library.restartPython()

Keep --no-deps alongside --force-reinstall — without it, pip reinstalls pyspark and other preinstalled packages and Serverless fails the cell. The second, plain install then restores any dependencies the first (deps-skipped) step left out.

Choose an extra for your runtime

GeoBrix Light uses explicit, runtime-pinned extras — every install picks a named, runtime-pinned extra. Pick the one that matches your compute:

RuntimeInstall commandFull feature set
Serverless env 6 (recommended)%pip install "geobrix[light_env6] @ file:///Volumes/…"geobrix[light_env6_all]
Serverless env 5%pip install "geobrix[light_env5] @ file:///Volumes/…"geobrix[light_env5_all]
Classic DBR 17.3%pip install "geobrix[light_dbr17] @ file:///Volumes/…"geobrix[light_dbr17_all]
Classic DBR 18%pip install "geobrix[light_dbr18] @ file:///Volumes/…"geobrix[light_dbr18_all]
Classic DBR 19%pip install "geobrix[light_dbr19] @ file:///Volumes/…"geobrix[light_dbr19_all]

(Full feature set = [light_envN/_dbrN] + [stac] + [vizx] + [overture] in one install. [databricks] is added separately if needed.)

The file:///Volumes/… path is a placeholder for the wheel on your Unity Catalog Volume — see the install steps below for the exact pattern including the PEP 508 package @ file:// quoting required on Serverless.

Upgrading from GeoBrix 0.4.x?

GeoBrix 0.4.x used a single unversioned extra: geobrix[light] (basic) or geobrix[light,stac,vizx] (with feature extras). In 0.5.0+ those bare extras are removed — every install names the target runtime explicitly. Replace [light] with the matching runtime extra from the table above (e.g. [light_env6] on Serverless, [light_dbr19] on classic DBR 19). Feature extras (stac, vizx, overture) are unchanged and still combine with the runtime extra.

:::

The lightweight tier is a single Python wheel installed with a runtime-pinned light extra (light_env6 on Serverless, light_dbrN on classic) — no init script, no JAR, no native GDAL bundle (rasterio's bundled GDAL does the work). It runs on serverless compute, standard (shared) clusters, Lakeflow declarative pipelines, and ARM. One wheel covers the whole lightweight tier: RasterX (the full rst_* set, via databricks.labs.gbx.pyrx), VectorX (via databricks.labs.gbx.pyvx), and GridX quadbin (via databricks.labs.gbx.pygx).

The wheel ships as a GitHub release artifact for GeoBrix 0.4.0+ — it is not published to PyPI. Install it from a Unity Catalog Volume so the same path works on both Serverless and Classic compute:

  1. Download geobrix-<version>-py3-none-any.whl from the GeoBrix releases (0.4.0 or later).
  2. Stage it in a Unity Catalog Volume your compute can read, e.g. /Volumes/<catalog>/<schema>/<volume>/geobrix/.
  3. Install it — either notebook-scoped with the %pip magic (installs across the whole cluster for the notebook session; plain pip installs only on the driver), or as a cluster-scoped library pointing at the same Volume path (works on Serverless and Classic):
%pip install "geobrix[light_env6] @ file:///Volumes/<catalog>/<schema>/<volume>/geobrix/geobrix-<version>-py3-none-any.whl"
Serverless install form

Use the quoted geobrix[light_env6] @ file://… form. Install with the PEP 508 named form above, wrapped in quotes as a single argument. Do not put the extra on the path ('/Volumes/…/geobrix-<version>-py3-none-any.whl[light_env6]'): on Serverless, %pip writes the requirement to a file including the surrounding quotes, so pip reads [light_env6] as part of the filename and fails with "Expected package name at the start of dependency specifier." The named form installs cleanly on Serverless, standard/shared, and ARM.

Then import the package(s) you need and (optionally) register their SQL functions. Each light package exposes the same functions / register(spark) pattern:

from databricks.labs.gbx.pyrx import functions as rx  # RasterX (rst_*)
# from databricks.labs.gbx.pyvx import functions as vx  # VectorX (st_*)
# from databricks.labs.gbx.pygx import functions as gx  # GridX quadbin (quadbin_*)

# optional — only needed to call the SQL functions:
rx.register(spark)

# Light DataSource readers (raster_gbx, gtiff_gbx, etc.) are Python DataSource
# V2 and aren't auto-discovered — register them explicitly when you need them:
# from databricks.labs.gbx.ds import register
# register.register(spark)

Verify the lightweight tier​

Confirm the wheel imports, rasterio's bundled GDAL is present, and a function runs end to end (no JAR, no init script). The check below exercises RasterX (rst_*); VectorX (pyvx, st_*) and GridX quadbin (pygx, quadbin_*) ship in the same wheel and register and run the same way:

import rasterio
from databricks.labs.gbx.pyrx import functions as rx

print("rasterio", rasterio.__version__, "| bundled GDAL", rasterio.__gdal_version__)

# Functional check: load a GeoTIFF and read its properties through pyrx.
tiles = (
    spark.read.format("binaryFile")
    .load("/Volumes/<catalog>/<schema>/<volume>/path/to/*.tif")
    .select(rx.rst_fromcontent("content", "GTiff").alias("tile"))
)
tiles.select(
    rx.rst_width("tile").alias("width"),
    rx.rst_height("tile").alias("height"),
    rx.rst_srid("tile").alias("srid"),
).show()

If the import succeeds and the query returns raster dimensions, the lightweight tier is ready. The rest of this page covers the heavyweight tier.