Skip to main content

​
Prerequisites

  • Python 3.10 or later
  • Node.js 18 or later and npm
If Node.js is not installed, use the official installer, Homebrew (brew install node), or conda (conda install -c conda-forge nodejs).

​
Step 1: Clone the repository and configure environment

1

Clone the repository

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor
2

Set up environment variables

cp .env.example .env
Open .env and fill in your API keys. The required variables are LLM_API_KEY, LLM_MODEL, LLM_HOST, EMBEDDING_API_KEY, EMBEDDING_MODEL, and EMBEDDING_HOST.See Environment variables for a full reference.

​
Step 2: Create a Python environment

​
Step 3: Install dependencies

On Windows, you may encounter errors about long file paths during npm install. See the Windows note below.

​
Step 4: Launch DeepTutor

python scripts/start_web.py
This command starts both the backend (FastAPI) and the frontend (Next.js) together. Once running, open your browser to: Press Ctrl+C to stop all services.

​
Starting services separately

If you need to run the backend and frontend in separate terminals — for example, to view their logs independently — start each one on its own. Backend (FastAPI) 
# Using the run server script
python src/api/run_server.py

# Or directly with uvicorn
uvicorn src.api.main:app --host 0.0.0.0 --port 8001 --reload
Frontend (Next.js) 
cd web && npm run dev -- -p 3782
Before starting the frontend separately, create web/.env.local so it knows where the backend is: 
NEXT_PUBLIC_API_BASE=http://localhost:8001
For remote or LAN access, replace localhost with the server’s IP address: 
NEXT_PUBLIC_API_BASE=http://192.168.1.100:8001

​
Default ports

ServiceDefault port
Backend (FastAPI)8001
Frontend (Next.js)3782
To change these defaults, set BACKEND_PORT and FRONTEND_PORT in your .env file before launching.

​
Windows: long path names

On Windows, npm install can fail with “The filename or extension is too long” due to the default 260-character path limit. Enable long path support by running the following command in an Administrator Command Prompt: 
reg add "HKLM\SYSTEM\CurrentControlSet\Control\FileSystem" /v LongPathsEnabled /t REG_DWORD /d 1 /f
Restart your terminal after running this command, then retry the installation.

Build docs developers (and LLMs) love

Get started for freeTalk to us