How to Install and Run DeepTutor Locally: A Step-by-Step Guide

This guide is based on the open-source project DeepTutor by HKUDS, licensed under Apache-2.0.

DeepTutor lets you run a personal tutor on your own machine, using your own study material rather than a generic hosted chatbot. This guide follows the current 1.7.0 layout; older releases use a different package layout.

What DeepTutor is, and who it is for

DeepTutor is a learning workspace, not just a chat window. You organise study around a workspace for a subject or project, then chat, quiz, solve problems, research, visualise concepts, follow a mastery path, or read a document with the tutor beside it.

It suits students, self-learners, teachers, and developers extending it with tools, skills, or knowledge bases. Its memory is inspectable: traces, curated facts, and cross-topic summaries are organised in layers you can review.

Prerequisites

Pick one path first; you only need its tools.

• PyPI, the recommended route: Python 3.11–3.14, Node.js 20 or newer on your PATH, a terminal, and a folder to use as your runtime home.
• Source: Python 3.11–3.14, Node.js 22 LTS, Git, and the same model choice as below.
• Docker: Docker installed and running. No Python or Node.js setup is needed for the trial itself.
• Model provider: an API key, an OAuth login such as OpenAI Codex or GitHub Copilot where supported, or a local server such as Ollama.
• Ports: backend 8001 and frontend 3782 by default; make sure they are free, or choose others during setup.
• Optional extras: an embedding model for knowledge bases, a search provider, and FFmpeg for transcription with the native DashScope or Volcengine adapters.

The README and handbook I checked do not publish a CPU or memory minimum for the app itself. If you run a large model locally, that model's requirements matter far more. Authentication is off by default.

Step 1: Choose a path, then install with PyPI

All paths share the same idea: pick a runtime-home directory, install, run the setup wizard, and start the app. Private settings live under data/user/settings/ inside that runtime home, unless you set DEEPTUTOR_HOME or pass --home to the launcher. Create a dedicated folder first:

mkdir -p my-deeptutor && cd my-deeptutor
pip install -U "deeptutor[full]"

The [full] part matters in 1.7.0: it requests the full web app and CLI, while bare deeptutor gives core chat only.

Run the interactive wizard:

deeptutor init

It asks for the ports, language-model provider, base URL, API key, and model, plus optional embedding and search providers. You can skip it for a quick trial, but without a model you will have an interface with nothing to answer you.

Step 2: Start the app and verify it

From the same runtime-home folder, run:

deeptutor start

Keep that terminal open. The launcher starts the backend and frontend together, and Ctrl+C stops both. Open the frontend address printed in the terminal, by default:

http://127.0.0.1:3782

In a second terminal, run the built-in health check:

deeptutor doctor
deeptutor doctor --online

The first checks local readiness; the second also makes a small real request to your provider, so it may incur a small amount of usage. If you used deeptutor start --detach, stop it later with deeptutor stop, using the same home if you set one explicitly.

Step 3: Configure an LLM provider

You can configure a model during deeptutor init, or afterwards in Settings → Providers and Language models. The web settings page uses a draft-and-apply flow, so you can test a provider before committing the change.

1. Open Settings → Providers and add a provider connection with its base URL and credential.
2. Open Language models, add the exact model ID, and select it as active.
3. If you plan to use knowledge bases, add an embedding profile as well.

Do not put your API key in a project-root .env file and expect DeepTutor to read it. The project states that project-root .env files are not loaded as application configuration. Use Settings → Providers instead, or the CLI flow below.

OpenAI-compatible and local providers

DeepTutor supports OpenAI-style APIs, and model profiles expose an API-format setting. Keep it on Auto unless you need to force OpenAI Chat Completions, OpenAI Responses, or Anthropic Messages, subject to provider support.

For a local model, point the base URL at your own server: Ollama's chat-style endpoint is http://127.0.0.1:11434/v1 when DeepTutor runs directly on the host, with a separate embedding endpoint. Make sure the server is running and the model is available first. LM Studio, llama.cpp, vLLM, and Lemonade are also named in the Docker guidance. Run deeptutor config providers for your version's exact list and provider IDs.

API Route, Codex OAuth, and Copilot

For API Route, select API Route in Settings → Providers, enter an API Route key, then add a model using its API Route model ID in Language models. The documented preset uses https://global.api-route.com/v1.

For OpenAI Codex, adding that provider opens a browser sign-in against your own ChatGPT plan, so no OPENAI_API_KEY is needed. GitHub Copilot uses deeptutor provider login github-copilot. Follow the in-app prompts for these routes.

Non-interactive setup

If you are scripting setup, write a JSON file naming the provider, model, ports, and the environment variable holding the key, rather than the key itself. Then validate and apply it:

deeptutor config apply setup.json --check
deeptutor config apply setup.json
deeptutor config show

The --check step validates the input, providers, credential references, endpoints, and port conflicts without writing settings. config show redacts credentials. For knowledge bases, add an embedding section; the handbook's example uses OpenAI's text-embedding-3-small with dimension 1536. Changing an existing base's embedding later may require a rebuild.

Alternative paths: Docker, source, and CLI only

Docker trial. This removes the Python and Node steps:

docker run --rm --name deeptutor \
  -p 127.0.0.1:3782:3782 \
  -v deeptutor-data:/app/data \
  ghcr.io/hkuds/deeptutor:latest

Open http://127.0.0.1:3782 and configure providers in Settings → Providers. The named volume keeps settings and data for the next run. Only port 3782 needs publishing for normal browser use.

Source install. For the current development branch, clone it, create a virtual environment, install requirements/full.txt and the package in editable mode, install the frontend with (cd web && npm ci --legacy-peer-deps), then run deeptutor init and deeptutor start --dev.

On Windows PowerShell, use py -3.11 -m venv .venv and .\.venv\Scripts\Activate.ps1. The --dev flag runs the frontend with hot reloading; without it, the launcher builds it once and reuses it.

CLI only. From a source checkout, skip Node and npm, then run deeptutor init --cli and deeptutor chat.

First run: a short walkthrough

Start with one workspace for one subject:

1. Chat: ask a grounded question about a document you have supplied, and check whether the answer cites it or asks a clarifying question when your request is vague.
2. Quiz: generate questions on the same topic, then check the question bank for reuse in practice and review.
3. Solve and Research: use Solve for a worked problem and Research for a cited report. These are separate capabilities, not just different prompts.
4. Knowledge base: upload one short document first. Retrieval problems are far easier to diagnose on a small base than after uploading a whole library.
5. Memory and tasks: check the memory view and Task Board, which tracks tasks as To do, In progress, and Done without needing model configuration.

If chat works but knowledge-base search does not, the problem is more likely to be in embedding or indexing than in the language model.

Common errors and fixes

These fixes are grounded in the official README or developer handbook. If yours is not listed, identify the exact instance, reproduce the symptom, and check deeptutor doctor and deeptutor config show before reinstalling.

For anything else, use the issue tracker with the version, reproduction steps, and redacted logs.

FAQ

Do I need an OpenAI account? No. You need a model provider, but it does not have to be OpenAI: another OpenAI-compatible provider, a local server such as Ollama, or an OAuth route such as OpenAI Codex or GitHub Copilot where supported will do. With no model configured, do not expect answers.

Is my study data stored locally? In a local install, private settings and state live in the data directory inside your runtime home, and Docker data persists in your chosen volume. A separate content workspace holds learning materials and generated files. If you use a hosted model API, your prompts still go to that provider under its terms.

Can I use DeepTutor without the web UI? Yes. Use deeptutor chat for an interactive terminal session, or deeptutor run <capability> "<message>" for a one-shot command. Add --format json for machine-readable output.

What should I do when upgrading? Stop the app, back up your runtime home, and keep the same DEEPTUTOR_HOME and settings. For 1.7.0, remember the [full] distinction and legacy CLI issue above; modules must match the core version.

Is DeepTutor a paid product? The README states that, as of the version checked here, the project does not have paid online products of any form. Running it is still not necessarily free: a hosted model or search provider, or hardware for a large local model, can have its own costs.

What to try next

Once the basics work, build one knowledge base from a document you study from, create a question bank from it, and set up a mastery path for a topic you keep getting wrong.

This guide was written with AI assistance and checked against the official documentation as of October 30, 2026.

Sources

• https://github.com/HKUDS/DeepTutor
• https://github.com/HKUDS/DeepTutor/blob/main/LICENSE
• https://github.com/HKUDS/DeepTutor/blob/main/docs-for-dev/AGENT_SETUP.md
• https://github.com/HKUDS/DeepTutor/blob/main/docs-for-dev/README.md
• https://deeptutor.info/
• https://github.com/HKUDS/DeepTutor/issues