# Prerequisites for Running Open Notebook: Complete Setup Guide

> Discover the essential prerequisites for running Open Notebook including Python, Node.js, Docker, Git, uv, and AI setup. Follow this complete guide for a smooth installation.

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

---

**You need Python 3.11+, Node.js 18+, Docker, Git, and the uv package manager installed, plus an AI provider API key or local LLM setup, to run the FastAPI backend, Next.js frontend, and SurrealDB database.**

Open Notebook is a multi-component application comprising a Python FastAPI backend, a Next.js (React) frontend, and a SurrealDB database. Before you can launch the services, you must install a specific set of development tools and runtime dependencies that cover all three layers. The authoritative requirements are documented in [`docs/1-INSTALLATION/from-source.md`](https://github.com/lfnovo/open-notebook/blob/main/docs/1-INSTALLATION/from-source.md) within the repository.

## Core Software Requirements

### Python Runtime

You must have **Python 3.11 or higher** installed to execute the FastAPI backend, async workers, and all Python packages. The backend entry point at [`api/main.py`](https://github.com/lfnovo/open-notebook/blob/main/api/main.py) relies on modern Python features available in 3.11+.

### Node.js Environment

**Node.js 18+** is required to power the Next.js frontend. The [`frontend/package.json`](https://github.com/lfnovo/open-notebook/blob/main/frontend/package.json) defines the npm scripts and dependencies that run the development server via `npm run dev`.

### Docker and Git

**Docker** (any recent version, including Docker Desktop or Engine) is essential for running the SurrealDB container used for storage and vector search. **Git** is needed to clone the repository and track changes.

### uv Package Manager

The project uses **uv** as its recommended Python package manager. Install it via the official script:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh

```

According to the source code in [`docs/1-INSTALLATION/from-source.md`](https://github.com/lfnovo/open-notebook/blob/main/docs/1-INSTALLATION/from-source.md), uv handles dependency resolution and virtual-environment creation significantly faster than traditional pip workflows.

## AI Provider Configuration

You need access to an AI model through one of these methods:

- **Cloud provider API key**: OpenAI or Anthropic keys enable the built-in multi-provider AI features.
- **Local LLM**: If you prefer a free local model, you can skip cloud keys and use **Ollama** instead.

This configuration is stored in your environment file, which you create from the provided template at `.env.example`.

## Step-by-Step Installation Checklist

Follow this sequence to prepare your environment:

1. **Install core tools**: Python 3.11+, Node 18+, Git, and Docker.
2. **Install uv**: Run the curl command above to get the Python package manager.
3. **Clone the repository**:
   ```bash
   git clone https://github.com/lfnovo/open-notebook.git
   cd open-notebook
   ```

4. **Create a virtual environment and install dependencies**:
   ```bash
   uv sync
   uv pip install python-magic   # optional dependency for file type detection

   ```

5. **Start SurrealDB** using the `Makefile` command:
   ```bash
   make database   # or: docker compose up surrealdb

   ```

6. **Configure environment variables**:
   ```bash
   cp .env.example .env
   ```

   Edit `.env` to set `OPEN_NOTEBOOK_ENCRYPTION_KEY` and any provider credentials.
7. **Launch the API backend**:
   ```bash
   make api   # spins up uvicorn on port 5055

   ```

8. **Start the frontend**:
   ```bash
   cd frontend && npm install && npm run dev
   ```

When successful, access the services at:
- Frontend: http://localhost:3000
- API documentation: http://localhost:5055/docs
- SurrealDB UI: http://localhost:8000

## Alternative Setup with Conda

If you prefer Conda over uv for environment management, use this workflow:

```bash
conda create -n open-notebook python=3.11 -y
conda activate open-notebook
conda install -c conda-forge uv nodejs -y
uv sync

```

This approach still leverages uv for dependency synchronization but wraps the environment in a Conda-managed Python installation.

## Key Configuration Files

| File | Purpose |
|------|---------|
| [`docs/1-INSTALLATION/from-source.md`](https://github.com/lfnovo/open-notebook/blob/main/docs/1-INSTALLATION/from-source.md) | Complete installation guide with prerequisites |
| `Makefile` | Task runner for commands like `make api` and `make start-all` |
| [`docker-compose.dev.yml`](https://github.com/lfnovo/open-notebook/blob/main/docker-compose.dev.yml) | Development Docker composition including SurrealDB |
| `.env.example` | Template for required environment variables |

## Summary

- **Python 3.11+**, **Node.js 18+**, **Docker**, and **Git** are mandatory system-level prerequisites.
- **uv** is the recommended Python package manager for handling dependencies and virtual environments.
- You must configure an **AI provider** (OpenAI, Anthropic, or Ollama) by setting keys in your `.env` file.
- The `Makefile` provides convenient commands like `make database` and `make api` to start services.
- Once configured, the stack runs on ports **3000** (frontend), **5055** (API), and **8000** (SurrealDB).

## Frequently Asked Questions

### Do I need a GPU to run Open Notebook?

No. Open Notebook does not require a GPU for standard operation. You can use cloud-based AI providers (OpenAI or Anthropic) for language model inference, or run local models via Ollama on CPU-only machines, though GPU acceleration will improve local model performance.

### Can I use Conda instead of uv for dependency management?

Yes. While uv is the recommended package manager, you can create a Conda environment with Python 3.11, install uv within that environment, and then run `uv sync` to install the project dependencies. This hybrid approach is documented in the [`docs/1-INSTALLATION/from-source.md`](https://github.com/lfnovo/open-notebook/blob/main/docs/1-INSTALLATION/from-source.md) guide.

### What ports need to be available?

You must ensure ports **3000**, **5055**, and **8000** are free on your local machine. Port 3000 serves the Next.js frontend, 5055 hosts the FastAPI backend and documentation, and 8000 exposes the SurrealDB management interface.

### Is a cloud AI API key mandatory?

No. A cloud API key is optional if you configure a local LLM using Ollama. The `.env.example` file supports both configurations, allowing you to set `OLLAMA_BASE_URL` for local inference or provider-specific keys (like `OPENAI_API_KEY`) for cloud services.