# How to Build and Run Open Notebook on macOS, Linux, and Windows

> Discover how to build and run Open Notebook on macOS, Linux, and Windows. Learn to use uv, Node.js, or Docker Compose for seamless development and deployment.

- Repository: [Luis Novo/open-notebook](https://github.com/lfnovo/open-notebook)
- Tags: getting-started
- Published: 2026-06-13

---

**You can build and run Open Notebook either from source using `uv` and Node.js for development, or via Docker Compose for a containerized deployment, with specific configuration adjustments required for Windows environments.**

Open Notebook is a three-tier research application by lfnovo/open-notebook that combines a FastAPI backend, Next.js frontend, and SurrealDB graph database. Depending on your operating system and whether you need to modify the source code, you can choose between a developer-friendly source installation or a containerized Docker deployment. This guide covers both methods for macOS, Linux, and Windows, including platform-specific fixes found in the official documentation.

## Architecture Overview

The application stack consists of three distinct services that must run simultaneously:

- **Frontend**: Next.js 16 (React 19) located in the `frontend/` directory, typically running on port **3000** (or **8502** in Docker Compose)
- **API**: FastAPI 0.104+ located in `api/` and `open_notebook/`, running on port **5055**
- **Database**: SurrealDB WebSocket interface on port **8000**

The frontend communicates with the FastAPI backend over HTTP, which persists data to SurrealDB via the WebSocket URL defined in your `.env` file (`SURREAL_URL`). All three services can be started independently, but the repository provides a `make start-all` command in the `Makefile` that orchestrates the correct startup sequence.

## Prerequisites by Operating System

Before building, ensure your system meets these requirements:

**macOS and Linux**
- Python 3.11+ and **uv** (the Python package manager)
- Node.js 18+
- Docker Desktop (for SurrealDB) or Docker Engine
- Git

Install `uv` on macOS with: `brew install uv` or via the official installer: `curl -LsSf https://astral.sh/uv/install.sh | sh`.

**Windows (Docker)**
- Git, Python 3.12+, Node.js 18+, and **uv**
- Docker Desktop for Windows
- Install via: `winget install Git.Git OpenJS.NodeJS` and `pip install uv`

**Windows (Native, No Docker)**
- Git, Python 3.12+, Node.js 18+, and **uv**
- SurrealDB installed via Scoop: `scoop install surrealdb`
- See [`docs/1-INSTALLATION/windows-native.md`](https://github.com/lfnovo/open-notebook/blob/main/docs/1-INSTALLATION/windows-native.md) for the complete checklist.

## Building from Source

Running from source is ideal for developers who need to modify the FastAPI backend or Next.js frontend. This method uses `uv` for Python dependency management and `npm` for Node.js packages.

### Step-by-Step Setup

1. **Clone the repository and install Python dependencies:**

```bash
git clone https://github.com/lfnovo/open-notebook.git
cd open-notebook
uv sync
uv pip install python-magic  # Required on some Linux distributions

```

2. **Configure the environment:**

```bash
cp .env.example .env

# Edit .env to set:

# - OPEN_NOTEBOOK_ENCRYPTION_KEY (generate a secure random string)

# - SURREAL_URL (use ws://127.0.0.1:8000/rpc on Windows)

```

3. **Start SurrealDB** using the Make target or Docker directly:

```bash
make database  # Runs: docker compose up -d surrealdb

```

4. **Launch the API backend:**

```bash
make api  # Runs: uv run --env-file .env run_api.py

```

5. **Start the background worker** (required for async jobs like podcast generation):

```bash
make worker-start

```

6. **Run the Next.js frontend:**

```bash
make frontend  # Runs: cd frontend && npm run dev

```

Access the application at `http://localhost:3000` (or `http://127.0.0.1:3000` on Windows).

### Using the Makefile

The `Makefile` at the repository root provides convenience targets that handle the virtual environment and working directories automatically. According to the source code in `Makefile` at lines 55-72, the `start-all` target launches the database, API, background worker, and frontend in the correct order:

```bash
make start-all

```

This single command is equivalent to running the database, API, worker, and frontend startup commands sequentially.

## Docker Compose Installation

For users who prefer containerization or want to avoid managing Python and Node.js environments locally, Docker Compose provides the simplest cross-platform solution.

1. **Download the official compose file:**

```bash
curl -o docker-compose.yml https://raw.githubusercontent.com/lfnovo/open-notebook/main/docker-compose.yml

```

2. **Edit the encryption key** (line 31 in the file):

```yaml
- OPEN_NOTEBOOK_ENCRYPTION_KEY=change-me-to-a-secret-string

```

3. **Start all services:**

```bash
docker compose up -d

```

4. **Access the services:**
   - Frontend: `http://localhost:8502`
   - API documentation: `http://localhost:5055/docs`
   - SurrealDB: `ws://localhost:8000/rpc`

The Docker Compose configuration automatically handles networking between the three tiers. On Windows, Docker Desktop automatically resolves `host.docker.internal` without requiring additional host entries.

## Native Windows Installation

If Docker is unavailable (e.g., on Windows ARM64 or systems without Hyper-V), follow the native Windows guide in [`docs/1-INSTALLATION/windows-native.md`](https://github.com/lfnovo/open-notebook/blob/main/docs/1-INSTALLATION/windows-native.md).

Critical Windows-specific configuration steps include:

1. **Update the database URL** in `.env` to use IP address instead of hostname:
   ```

   SURREAL_URL="ws://127.0.0.1:8000/rpc"
   ```

   This change is documented in [`docs/1-INSTALLATION/windows-native.md`](https://github.com/lfnovo/open-notebook/blob/main/docs/1-INSTALLATION/windows-native.md) at lines 46-51 and prevents "database health check timed out" errors caused by `localhost` resolution issues.

2. **Create a batch launcher** (`start-open-notebook.bat`) that sets the `ROOT` and `DATA_FOLDER` environment variables, then launches components using `uv run`:

```batch
set ROOT=%~dp0
set DATA_FOLDER=C:\open-notebook-data
uv run --env-file .env python -m surreal_commands.cli.worker --import-modules commands
uv run --env-file .env run_api.py
cd frontend && npm install && npm run dev

```

3. **Use `uv run` exclusively** rather than activating virtual environments manually. As noted in [`docs/1-INSTALLATION/windows-native.md`](https://github.com/lfnovo/open-notebook/blob/main/docs/1-INSTALLATION/windows-native.md) at lines 91-99, invoking Python directly without `uv run` causes `ModuleNotFoundError` because the system Python lacks the project's dependencies.

## Troubleshooting Common Issues

| Symptom | Cause | Solution |
|---------|-------|----------|
| `ModuleNotFoundError: No module named 'langgraph.checkpoint.sqlite'` | System Python used instead of `uv` virtualenv | Prefix all Python commands with `uv run` (see [`docs/1-INSTALLATION/windows-native.md`](https://github.com/lfnovo/open-notebook/blob/main/docs/1-INSTALLATION/windows-native.md) lines 91-99) |
| Database health check timeout | `.env` uses `localhost` while SurrealDB binds to `127.0.0.1` | Change `SURREAL_URL` to `ws://127.0.0.1:8000/rpc` (see [`docs/1-INSTALLATION/windows-native.md`](https://github.com/lfnovo/open-notebook/blob/main/docs/1-INSTALLATION/windows-native.md) lines 11-21) |
| Worker fails to locate `commands` module | `PYTHONPATH` not set in Windows batch script | Set `PYTHONPATH` to the project root before launching the worker (see [`docs/1-INSTALLATION/windows-native.md`](https://github.com/lfnovo/open-notebook/blob/main/docs/1-INSTALLATION/windows-native.md) lines 31-38) |
| Docker on Linux cannot reach `host.docker.internal` | Linux Docker lacks this hostname by default | Add `extra_hosts: - "host.docker.internal:host-gateway"` to [`docker-compose.yml`](https://github.com/lfnovo/open-notebook/blob/main/docker-compose.yml) |

## Summary

- **Open Notebook** consists of a FastAPI backend (port 5055), Next.js frontend (port 3000/8502), and SurrealDB (port 8000).
- **Source installation** requires `uv`, Node.js, and Docker for the database; use `make start-all` to orchestrate startup.
- **Docker Compose** offers the simplest cross-platform deployment with pre-configured networking.
- **Windows users** must change `SURREAL_URL` to `ws://127.0.0.1:8000/rpc` and use `uv run` for all Python commands.
- **Linux users** running Docker may need to add `extra_hosts` to resolve `host.docker.internal` when connecting to host services like Ollama.

## Frequently Asked Questions

### Can I run Open Notebook on Windows without Docker?

Yes. The repository includes a native Windows installation guide at [`docs/1-INSTALLATION/windows-native.md`](https://github.com/lfnovo/open-notebook/blob/main/docs/1-INSTALLATION/windows-native.md) that uses `uv` for Python package management and Scoop to install SurrealDB directly on your system. You must modify the `.env` file to use `127.0.0.1` instead of `localhost` for the database connection and create a batch file to set environment variables before launching the services.

### What is the difference between running from source and using Docker Compose?

Running from source is intended for developers who need to modify the FastAPI backend (`api/`) or Next.js frontend (`frontend/`). It requires installing Python, Node.js, and `uv` locally, and launches the frontend on port 3000. Docker Compose is a pre-configured, production-ready setup that bundles all three services into containers, exposes the frontend on port 8502, and requires no local runtime installations beyond Docker itself.

### Why does the database connection fail on Windows with "localhost"?

Windows networking stacks often resolve `localhost` differently than `127.0.0.1`, causing the SurrealDB WebSocket connection to fail. According to the Windows native installation documentation, you must explicitly set `SURREAL_URL="ws://127.0.0.1:8000/rpc"` in your `.env` file to ensure the FastAPI backend can reach the database.

### How do I update Open Notebook to the latest version?

For source installations, run `git pull` to fetch the latest code, then `uv sync` to update Python dependencies, and `cd frontend && npm install` to refresh Node.js modules. For Docker Compose deployments, pull the updated [`docker-compose.yml`](https://github.com/lfnovo/open-notebook/blob/main/docker-compose.yml) file and run `docker compose up -d` to recreate the containers with the latest images.