> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quadrillion.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Notebooks

> A Jupyter-compatible notebook IDE with code execution and visualizations.

Qualia is a complete Jupyter-compatible notebook IDE. Everything you create is saved as standard `.ipynb` files that work in JupyterLab, VS Code, or any other notebook tool.

Notebook-mode agents work directly with the open notebook's cells and kernel. For standalone scripts, batch jobs, or long-running training, set the default agent execution mode to **Script** in **Settings > General** before creating the agent.

## Creating and managing notebooks

* Click **New Notebook** in the Files sidebar to create a notebook
* Open existing `.ipynb` files by clicking them in the file browser
* Open multiple notebooks in [tabs](/tabs) and switch between them
* Rename, duplicate, or delete files by right-clicking in the sidebar

## Uploading and downloading files

Move files between your machine and the workspace from the Files sidebar:

* **Upload** — click the upload button in the sidebar toolbar, right-click a folder and choose **Upload files…**, or drag files from your machine onto the sidebar. Uploads with a name that already exists are renamed automatically (`name (1).ext`). Uploads travel through the app and are capped at 288 MB per file; cloud workspaces backed by durable workspace storage upload straight to storage instead, which raises the limit to 5 GB per file and shows upload progress.
* **Download** — right-click a file and choose **Download**. This appears when the workspace runs somewhere other than your machine (e.g. a cloud workspace); for local workspaces, use **Reveal in Finder/File Explorer** instead.

## Exporting and importing projects

A whole project — its sessions, tasks, knowledge, notebooks, and images (chat attachments and figure evidence) — can be exported as a single `.qualia` archive from the project menu in the Files sidebar, and imported back on any workspace, local or cloud. Choosing **Export .qualia** opens a dialog where you confirm what goes in the archive; in the desktop app you then pick a folder and Qualia writes the archive into it, showing progress while it works. If some notebooks or images can't be read at export time, the export still completes and warns you how many were left out. Importing always creates a new project; on cloud workspaces, imported sessions start out idle instead of resuming where they left off.

Images travel with the archive on local workspaces only. Cloud workspaces store images outside the project transfer path, so exporting from or importing into one leaves them behind — the archive is still valid, and both the export and the import tell you which images are missing.

### Including the whole workspace

The export dialog's **Include workspace files** switch adds every other file in the workspace — data files, scripts, and modules your notebooks read — to the same archive, so the imported project can actually run. The exported project data is unchanged: one project's sessions, tasks, and knowledge, never a sibling project's.

It is not a byte-for-byte copy of the folder. Qualia leaves out things that are rebuildable or private: package caches, virtual environments (`.venv`, `venv`), version-control folders (`.git`, `.hg`, `.svn`), `node_modules`, `__pycache__`, notebook checkpoints, credential folders such as `.ssh` and `.aws`, credential files such as `.netrc`, `.npmrc`, and `.git-credentials`, and OS clutter like `.DS_Store`. It does keep output folders such as `out/`, `build/`, and `dist/`, and it keeps `.log` files, because those are often where your results actually are. It also keeps `.env` files, since the imported project usually needs them to run. Symlinks are never followed. Be careful who you share one of these with — it carries everything else in the folder, not just the project.

The switch appears in the desktop app when your workspace is on the same machine, because Qualia writes the archive straight into a folder you pick: these archives can be many gigabytes, which is more than a browser can hold, and the folder you pick has to be one the workspace can see. Choose **Export .qualia**, pick a folder, and Qualia writes the file there while showing progress. Everywhere else — the browser, or a workspace on another machine — **Export .qualia** downloads the project data on its own.

On import, workspace files are written only where nothing exists yet — a file already in the destination workspace is left exactly as it is and reported as skipped. Move or rename anything you want replaced before importing. If a file cannot be written into the destination at all — a name that this operating system does not allow, or a file too large for a cloud workspace — the rest of the import still completes and the file is named in a warning.

Archives record the database schema version they were exported against. Importing an archive from an older version of Qualia works — the data is upgraded on the way in — and an archive from a newer build imports fine as long as that build did not change the schema. If the archive needs a schema this copy of Qualia does not have, the import is refused; update Qualia and try again.

## Cell types

* **Code cells**: Python, R, or Julia with syntax highlighting, bracket matching, and auto-indentation
* **Markdown cells**: Rich text with LaTeX math support via KaTeX
* **Raw cells**: Unformatted text passed through as-is (e.g., for nbconvert)

## Adding cells

There are several ways to add new cells:

* **Click the + button** between cells or at the bottom of the notebook
* **Press A** (in command mode) to insert a cell above the current cell
* **Press B** (in command mode) to insert a cell below the current cell
* **Press Alt+Enter** to run the current cell and insert a new cell below
* **Click the cell type buttons** (Code, Markdown, Raw) in the toolbar to add that type

New cells are code cells by default. Convert them with **M** (markdown), **Y** (code), or **R** (raw) in command mode.

## Running cells

| Shortcut           | Action                             |
| ------------------ | ---------------------------------- |
| **Shift+Enter**    | Run cell and move to next          |
| **Cmd/Ctrl+Enter** | Run cell and stay                  |
| **Alt+Enter**      | Run cell and insert new cell below |

## Kernel toolbar

The toolbar at the top of each notebook controls the kernel:

* **Kernel picker**: Click to choose Python, R, or Julia environments
* **Interrupt**: Stop running code
* **Restart**: Clear kernel state and start fresh
* **Run all**: Execute all cells in order

See [Kernel Toolbar](/kernel-toolbar) for the full list of actions.

## Cell operations

In **command mode** (press Escape first):

| Key                   | Action                               |
| --------------------- | ------------------------------------ |
| **A** / **B**         | Insert cell above / below            |
| **D, D**              | Confirm deletion of the current cell |
| **M** / **Y** / **R** | Convert to markdown / code / raw     |
| **C** / **V**         | Copy / paste cell                    |
| **Shift+M**           | Merge selected cells                 |
| **J/K** or arrows     | Navigate between cells               |

Press **Enter** to return to edit mode.

Deleting a cell asks for confirmation because cell deletion cannot be undone.

## Code navigation

When the Python language server is enabled in settings, code cells and text
files support jumping around your code:

| Key                                                      | Action                                              |
| -------------------------------------------------------- | --------------------------------------------------- |
| **F12** or **Cmd/Ctrl+click**                            | Go to the definition of the symbol under the cursor |
| **Shift+F12**                                            | List all references to the symbol in a popup        |
| **Ctrl+-** (macOS) / **Alt+Left** (Windows/Linux)        | Go back to where you jumped from                    |
| **Ctrl+Shift+-** (macOS) / **Alt+Right** (Windows/Linux) | Go forward again after going back                   |

Targets in the same notebook scroll to and select the right cell; targets in
other files open that file at the selected location. The references popup
shows a preview line for each result — click one (or use the arrow keys and
Enter) to jump to it. After a jump, **Go → Back** (or its shortcut) returns
to the position you came from, hopping across cells and files as needed.

## Outputs

Qualia renders all standard Jupyter output types: text, tables (pandas DataFrames), plots (matplotlib, plotly, seaborn), images, interactive widgets (ipywidgets), and error tracebacks.

## Image viewer

Click any image — a plot output, an image in a markdown cell, an image sent in [chat](/chat-and-ai), a figure in the [knowledge graph](/knowledge), or an image file in the Explorer — to open it in the image viewer tab. From there you can:

* **Zoom and pan** — use the toolbar buttons or presets, **Cmd/Ctrl+scroll**, or **Cmd/Ctrl +/−/0**. Hold **Cmd/Ctrl** and drag to pan while zoomed in.
* **Select a region** — drag to highlight part of the image. Press **Escape** or use **Clear** to deselect.
* **Copy, download, or attach** — right-click (or use the toolbar) to copy the image or selection to the clipboard, download it, or attach it to a chat. Images from a notebook attach to that notebook's agent; images from a chat return to that conversation.

## Saving and autosave

Press **Cmd/Ctrl+S** to save the notebook to its `.ipynb` file. Unsaved work is
also kept in a durable draft that survives app restarts, so closing or crashing
never loses edits — saving controls when changes land in the file itself.

Turn on **Notebook autosave** (a beta feature) in Settings → Notebooks to save
the file automatically a couple of seconds after you stop editing. While
autosave is on:

* The toolbar shows a **Saving… / Saved** status, or **File changed on disk**
  while a conflict with the file is waiting on your decision
* Closing a notebook with unsaved changes saves it silently instead of prompting
* If the file was changed outside Qualia (for example by an external editor or
  `git checkout`), autosave pauses and asks whether to overwrite the file or
  discard your draft — it never overwrites external changes silently
* If you open the same notebook in two windows and edit in both, autosave from
  one window is treated as an external change by the other, which pauses and
  prompts the same way — edit a notebook in one window at a time to avoid this

Autosave is off by default.

## Find in notebook

Press **Cmd/Ctrl+F** to search within the current notebook. Supports case-sensitive matching, whole-word matching, and regular expressions. See [Search](/search) for details.

## File export

Export notebooks as standalone files with all variable references resolved. When you export, [qualia evidence reads](/q-vars) (`qualia.get(...)` and the R/Julia equivalents) are replaced with actual values, making the notebook fully self-contained and runnable without Qualia.

## Related

* [Kernel Toolbar](/kernel-toolbar) — kernel selection, interrupt, restart, run all
* [Search](/search) — find in notebook and across files
* [Terminal](/terminal) — integrated shell
* [Matplotlib Settings](/settings/matplotlib) — plot styling
* [Cell Tags](/settings/tags) — organize cells with tags