# How to Install DeepTutor Locally: 4 Methods from Guided Setup to Docker

> Learn how to install DeepTutor locally with 4 easy methods including guided setup and Docker. Get started with HKUDS/DeepTutor today.

- Repository: [✨Data Intelligence Lab@HKU✨/DeepTutor](https://github.com/HKUDS/DeepTutor)
- Tags: how-to-guide
- Published: 2026-04-08

---

**To install DeepTutor locally, clone the HKUDS/DeepTutor repository, create a Python 3.11 environment, and either run the interactive `python scripts/start_tour.py` for automatic configuration, or manually install dependencies with `pip install -e ".[server]"` and `npm install` in the `web` directory.**

DeepTutor is an agent-native tutoring platform built on a two-layer plugin architecture (Tools and Capabilities) that powers a FastAPI backend, a Next.js frontend, and a rich CLI. This guide walks through four distinct installation pathways based on the official source code, covering the automated Setup Tour, manual installation, Docker deployment, and CLI-only usage.

## Prerequisites for Local Installation

Before installing DeepTutor, ensure your system meets these baseline requirements:

- **Python 3.11** – The runtime specifically targets Python 3.11 for compatibility with the agent orchestration layer.
- **Node.js** – Required for the Next.js frontend located in the `web/` directory.
- **Git** – To clone the HKUDS/DeepTutor repository.
- **Docker** (optional) – Only needed if you choose the containerized deployment path.

## Method 1: Guided Setup Tour (Recommended)

The Setup Tour is the fastest way to get started. The [`scripts/start_tour.py`](https://github.com/HKUDS/DeepTutor/blob/main/scripts/start_tour.py) script handles dependency installation, environment configuration, and temporary server initialization automatically.

### Step 1: Clone the Repository

```bash
git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor

```

### Step 2: Create a Python 3.11 Environment

```bash
conda create -n deeptutor python=3.11 && conda activate deeptutor

# Or using venv:

python -m venv .venv && source .venv/bin/activate

```

### Step 3: Run the Interactive Installer

The installer checks for system dependencies (including Math Animator requirements) and installs Python and Node modules:

```bash
python scripts/start_tour.py

```

### Step 4: Configure Providers via Browser

During execution, the script prompts you to:

- Select a **profile** (`web-basic` or `web-rag`).
- Confirm backend (default `8001`) and frontend (default `3782`) ports.
- Automatically open `http://localhost:<frontend_port>/settings?tour=true` to enter LLM, embedding, and search provider credentials.

Once you click **"Complete & Launch"**, DeepTutor starts automatically on your specified ports.

## Method 2: Manual Local Installation

For full control over the configuration process or CI/CD integration, install each component manually according to the structure defined in [`deeptutor/runtime/orchestrator.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/runtime/orchestrator.py) and the registry files.

### Install Python Dependencies

From the repository root:

```bash
pip install -e ".[server]"

```

This command installs the FastAPI backend, CLI tools, and optional RAG dependencies defined in [`requirements/server.txt`](https://github.com/HKUDS/DeepTutor/blob/main/requirements/server.txt).

### Install Frontend Dependencies

```bash
cd web
npm install
cd ..

```

### Configure Environment Variables

Copy the template and edit the required fields:

```bash
cp .env.example .env

```

Edit `.env` to set at minimum:

- `LLM_BINDING`, `LLM_MODEL`, `LLM_API_KEY`, `LLM_HOST`
- `EMBEDDING_BINDING`, `EMBEDDING_MODEL`, `EMBEDDING_API_KEY`, `EMBEDDING_HOST`
- `SEARCH_PROVIDER` and `SEARCH_API_KEY` (optional)

### Start the Services

Run the backend and frontend in separate terminals:

```bash

# Terminal 1 - Backend (port 8001 by default)

python -m deeptutor.api.run_server

# Terminal 2 - Frontend (port 3782)

cd web && npm run dev -- -p 3782

```

## Method 3: Docker Deployment

For a containerized installation that requires no local Python or Node installation, use the pre-built images via [`docker-compose.ghcr.yml`](https://github.com/HKUDS/DeepTutor/blob/main/docker-compose.ghcr.yml).

```bash
git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor
cp .env.example .env

# Edit .env with your API keys and port preferences

docker compose -f docker-compose.ghcr.yml up -d

```

The compose file mounts `./data` for persistent storage of knowledge bases and user memory. To build locally instead of using the pre-built image, run `docker compose up -d` without the `-f docker-compose.ghcr.yml` flag.

## Method 4: CLI-Only Installation

If you only need the terminal interface without the web UI, install the lightweight CLI package:

```bash
git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor
conda create -n deeptutor python=3.11 && conda activate deeptutor
pip install -e ".[cli]"

```

The CLI entry point in [`deeptutor_cli/main.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor_cli/main.py) registers sub-commands for agent interaction and knowledge base management:

```bash

# Interactive REPL

deeptutor chat

# Single command execution

deeptutor run chat "Explain the Fourier transform"

# Knowledge base operations

deeptutor kb create my-kb --doc paper.pdf

```

## How the Architecture Supports Local Deployment

DeepTutor's runtime is orchestrated by `ChatOrchestrator` in [`deeptutor/runtime/orchestrator.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/runtime/orchestrator.py), which routes requests between **Tools** (single-function utilities) and **Capabilities** (multi-step agent pipelines). These are discovered dynamically by [`tool_registry.py`](https://github.com/HKUDS/DeepTutor/blob/main/tool_registry.py) and [`capability_registry.py`](https://github.com/HKUDS/DeepTutor/blob/main/capability_registry.py), allowing the local installation to function immediately after environment variables are configured, without additional manual registration of components.

## Summary

- **Setup Tour**: Run `python scripts/start_tour.py` for an automated, browser-guided installation that handles Python 3.11 setup, dependency installation, and provider configuration.
- **Manual Install**: Use `pip install -e ".[server]"` and `npm install` in `web/` for full control over the FastAPI backend and Next.js frontend startup process.
- **Docker**: Execute `docker compose -f docker-compose.ghcr.yml up -d` after configuring `.env` for a zero-dependency local deployment with persistent `./data` storage.
- **CLI-Only**: Install with `pip install -e ".[cli]"` to access the terminal interface defined in [`deeptutor_cli/main.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor_cli/main.py) without running the web server.

## Frequently Asked Questions

### What Python version does DeepTutor require?

DeepTutor requires **Python 3.11** specifically. The agent orchestration layer and dependency stack in [`requirements/server.txt`](https://github.com/HKUDS/DeepTutor/blob/main/requirements/server.txt) are tested against this version. Using older Python versions may result in compatibility errors with the async runtime used by `ChatOrchestrator`.

### Which environment variables are mandatory to start DeepTutor?

At minimum, you must configure **LLM** and **embedding provider** variables in `.env`: `LLM_BINDING`, `LLM_MODEL`, `LLM_API_KEY`, `LLM_HOST`, plus `EMBEDDING_BINDING`, `EMBEDDING_MODEL`, `EMBEDDING_API_KEY`, and `EMBEDDING_HOST`. Search provider keys are optional unless using the `web-rag` profile that queries external search APIs.

### Can I use DeepTutor without installing Node.js?

Yes. If you skip the web frontend, install only the CLI with `pip install -e ".[cli]"` and interact via the terminal using commands from [`deeptutor_cli/main.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor_cli/main.py). Alternatively, use the **Docker deployment** method, which bundles the Node.js frontend inside the container without requiring a local Node installation.

### How do I update my local DeepTutor installation?

For manual installations, pull the latest changes with `git pull` and reinstall Python dependencies with `pip install -e ".[server]" --upgrade`. For Docker deployments, run `docker compose -f docker-compose.ghcr.yml pull` followed by `docker compose up -d` to fetch the latest pre-built images. The Setup Tour users should re-run `python scripts/start_tour.py` after pulling updates to ensure [`requirements/server.txt`](https://github.com/HKUDS/DeepTutor/blob/main/requirements/server.txt) changes are applied.