Install from Source

For development against a checkout. Use Python 3.11–3.13 and Node.js 22 LTS to match CI and Docker.

Install

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

# Create a venv (macOS / Linux)
# Windows PowerShell:
#   py -3.11 -m venv .venv ; .\.venv\Scripts\Activate.ps1
python3 -m venv .venv && source .venv/bin/activate
python -m pip install --upgrade pip

# Install backend + frontend deps
python -m pip install -e .
( cd web && npm ci --legacy-peer-deps )

deeptutor init
deeptutor start

Source installs run Next.js in dev mode against the local web/ directory; everything else (config layout, ports, stop with Ctrl+C) matches the PyPI install.

Conda instead of venv

conda create -n deeptutor python=3.11
conda activate deeptutor
python -m pip install --upgrade pip
# ...then continue with `pip install -e .` and `npm ci`

Optional install extras

pyproject.toml exposes layered extras:

pip install -e ".[dev]"             # tests / lint tools
pip install -e ".[partners]"        # all Partner channel SDKs (incl. wecom-aibot-sdk) + MCP client
pip install -e ".[matrix]"          # Matrix channel without E2EE / libolm
pip install -e ".[matrix-e2e]"      # Matrix E2EE; requires libolm
pip install -e ".[math-animator]"   # Manim addon; requires LaTeX / ffmpeg / system libs

Compose them: pip install -e ".[dev,partners,math-animator]".

Full list — each extra has a requirements/*.txt mirror for Docker/CI builds where the source tree isn’t available yet:

Extra	What it adds	Requirements mirror
`cli`	Compatibility extra — CLI deps, already included in the default install	`requirements/cli.txt`
`server`	Compatibility extra — FastAPI server deps, already included in the default install	`requirements/server.txt`
`partners`	Every built-in Partner channel SDK (`wecom-aibot-sdk`, `qq-botpy`, `slack-sdk`, `lark-oapi`, `python-telegram-bot`, `dingtalk-stream`, …) + MCP client	`requirements/partners.txt`
`tutorbot`	Legacy alias for `partners`, kept for one release	—
`matrix`	Matrix (Element) channel, non-E2EE — works without libolm	`requirements/matrix.txt`
`matrix-e2e`	Matrix E2EE add-on — needs the system libolm library	`requirements/matrix-e2e.txt`
`math-animator`	Manim addon — needs LaTeX, pkg-config, cairo, cmake, ffmpeg	`requirements/math-animator.txt`
`dev`	pytest / pre-commit / lint & security tooling	`requirements/dev.txt`
`all`	`partners` + `matrix` + `math-animator` + `dev` (E2EE not included)	—

System dependencies for some extras

Extra	System library
`matrix-e2e`	libolm: `brew install libolm` (macOS) / `sudo apt install libolm-dev` (Debian)
`math-animator`	LaTeX + ffmpeg: `brew install --cask mactex && brew install ffmpeg` (macOS) / `sudo apt install texlive-full ffmpeg` (Linux)

Frontend dependency tweaks

When you add or upgrade a frontend dependency:

cd web
npm install --legacy-peer-deps
# commit both web/package.json and web/package-lock.json

Dev-server troubleshooting

Stuck dev server: if deeptutor start reports an existing frontend that isn’t responding, stop the PID it prints. If no Next.js process is actually running, the lock files are stale — remove them and retry:

rm -f web/.next/dev/lock web/.next/lock
deeptutor start

Hot reload

The backend supports --reload. Start backend and frontend in separate terminals for the best dev loop:

# Terminal A — backend with hot reload
python -m uvicorn deeptutor.api.main:app \
  --host 0.0.0.0 --port 8001 \
  --reload --reload-exclude "web/*" --reload-exclude "data/*"

# Terminal B — frontend dev server
cd web && npm run dev -- -p 3782

Updating

git pull
pip install -e . --upgrade
cd web && npm ci --legacy-peer-deps

If a release bumped settings schema, also re-run deeptutor init to fill in newly-introduced fields. Existing config is preserved.

Common errors

`error: Microsoft Visual C++ 14.0 is required` (Windows)

Some Python deps compile C extensions. Install Build Tools for Visual Studio with “Desktop development with C++”.

`libolm` not found (when `matrix-e2e` is installed)

brew install libolm                   # macOS
sudo apt install libolm-dev           # Debian / Ubuntu
pip install -e ".[matrix-e2e]" --force-reinstall

`npm ci` slow or times out

npm config set fetch-timeout 600000
cd web && npm ci --legacy-peer-deps

Backend `--reload` thrashes on every save

You forgot the --reload-exclude flags. Restart with:

python -m uvicorn deeptutor.api.main:app \
  --host 0.0.0.0 --port 8001 \
  --reload --reload-exclude "web/*" --reload-exclude "data/*"

More fixes: Troubleshooting.

DeepTutor CLI — drive the CLI from the same workspace
Explore DeepTutor — tour the running app