# Notebook sessions (/notebooks/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](/notebooks/querying-data) covers what to do once
you are inside.

<Callout title="Prerequisite">
  You need the `can_use_notebooks` permission, checked at sign-in — see [the note below](#a-grant-applies-at-your-next-sign-in).
</Callout>

## 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](/notebooks/storage).

## 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](/notebooks/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](/notebooks/files-and-arrays) |
| `pylakekeeper` | The catalog's own client |
| `trino`, `sqlalchemy` | SQL clients |
| `marimo` | Reactive notebooks |
| `jupyterlab-git` | The Git panel — see [working with Git](/notebooks/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](https://wolkwork.github.io/databaas-utils/).

## 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](https://jupyterlab.readthedocs.io/en/stable/).
- A **marimo** notebook, reactive: cells re-run when their inputs change. It is stored as a plain
  `.py` file, so it diffs cleanly in git. See the [marimo documentation](https://docs.marimo.io/).

## 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](/notebooks/querying-data#scan-rows). 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](/notebooks/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](/access/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](/catalog/data-permissions).