Notebook sessions
Start, use, and stop your notebook server.
Notebooks gives you a private Python server next to the lakehouse. This page covers starting it, what it comes with, and stopping it; querying data covers what to do once you are inside.
Prerequisite
You need the can_use_notebooks permission, checked at sign-in — see the note below.
Open your notebook server
Open Notebooks from the portal. If your server is not running, Databaas starts one for you, which can take a minute; JupyterLab opens when it is ready. The server is yours alone: nobody else runs code in it or sees your home folder.
What is installed
Everything you need for the lakehouse is already in the environment, with nothing to install:
| Package | Use it for |
|---|---|
databaas-utils | Your catalog, tokens and file stores, under your own login — see querying data |
pyiceberg (with pyarrow and s3fs) | Reading and writing Iceberg tables |
duckdb, duckdb-engine | SQL over data in your session |
pandas, polars, pyarrow | DataFrames and Arrow tables |
altair | Charts |
zarr, obstore | Arrays and files — see files, blobs and Zarr arrays |
pylakekeeper | The catalog’s own client |
trino, sqlalchemy | SQL clients |
marimo | Reactive notebooks |
jupyterlab-git | The Git panel — see working with Git |
databaas-utils is already installed for every kernel; it is not a file in your home directory, so
you will not see it in the file browser. Run help(databaas_utils.notebook) after importing it for
its full documentation, or read the databaas-utils documentation.
Choose Jupyter or marimo
Both run Python and reach the lakehouse through the same helpers, and both have a tile in the JupyterLab launcher:
- A Jupyter notebook (
.ipynb) in JupyterLab, which opens by default. See the JupyterLab documentation. - A marimo notebook, reactive: cells re-run when their inputs change. It is stored as a plain
.pyfile, so it diffs cleanly in git. See the marimo documentation.
Resources
By default each notebook server is guaranteed 1 GB of memory and can use up to 4 GB, and is guaranteed 0.25 CPU and can burst up to 2 CPUs. Everything you load into a DataFrame counts against that memory, so narrow a scan before you load it — see querying data. If you need more, ask your platform administrator.
Stop and restart
Your files persist when the server stops, so stopping is safe — see notebook storage. Stop it explicitly from the JupyterHub control panel (File → Hub Control Panel → Stop My Server); reopening Notebooks starts a fresh server. Restart if a session gets into a bad state — a stuck kernel or memory that has run out.
A grant applies at your next sign-in
Notebooks is the one feature whose permission is read at sign-in, not on every request. A grant applies at your next sign-in to Notebooks. A revoke also applies at the next sign-in: a server that is already running keeps running. See how access works.
Data access is different: your catalog grants are checked on every query, so a new data grant works in a running notebook straight away. See data permissions.