HKUDS DeepTutor

1. What is DeepTutor?

DeepTutor is an AI tutor that runs on your own computer and opens in a web browser. You give it study material (books, lecture notes, your own notes) and then ask questions, get step-by-step solutions, generate quizzes, research a topic, draw explanatory diagrams or follow a learning path. You can also paste a YouTube link and ask questions tied to exact moments in the video. It is developed by the HKUDS group and is open source under the Apache-2.0 license.

The software is free. But DeepTutor does not ship with an AI "brain": you must connect it to a language model, either through an API key from a provider (usually billed by usage) or through a model running on your own machine with something like Ollama or LM Studio.

To be direct: there is no .exe or .dmg installer yet. You install it with a few commands. The steps are not hard, but you do have to type them.

A good fit if:

• You are a student or self-learner who wants one place to collect material, ask questions and practise.
• You are willing to type three or four commands and get an API key.
• You want your study data to stay on your own machine.

Not a good fit if:

• You only have a phone. DeepTutor installs on a computer.
• You want to download, double-click and go, with nothing to configure.
• You do not want an API key and cannot run an AI model locally.

2. What do you need?

Item	Details
Computer	Windows, macOS or Linux.
Python 3.11 to 3.14	The programming language DeepTutor's core runs on. Download: https://www.python.org/downloads/ . On Windows, tick "Add python.exe to PATH" during install.
Node.js 20 or newer	The runtime for the web interface. Download: https://nodejs.org/
A language model	An API key from a provider (usually paid by usage; check the provider's pricing page), or a local model through Ollama, LM Studio, llama.cpp, vLLM or Lemonade.
An embedding model	Optional. Only needed for the Knowledge Base feature (questions answered from your own documents).
Docker Desktop	Optional. Only needed for Route B. Docker runs an application inside a pre-packaged "container". Download: https://www.docker.com/products/docker-desktop/
Internet	Needed to install and to call an AI model over an API.

The project docs do not state minimum RAM or disk space. More documentation is at https://deeptutor.info/

3. Step-by-step installation

The project offers four install paths. This guide covers the two that suit beginners: Route A installs from PyPI (the Python package index), Route B uses Docker. The other two (from source, and a command-line-only build) are for developers; see the project README.

Step 1 (Route A): Check Python and Node.js

After installing Python and Node.js, type these one at a time:

python --version
node --version

What success looks like: the first prints a Python version between 3.11 and 3.14, the second prints a Node version of v20 or higher. On macOS and Linux, try python3 if python is not found.

Step 2 (Route A): Make a dedicated folder and install

DeepTutor stores its settings and data inside the folder you start it from. So create a dedicated folder and always launch from there.

Windows (PowerShell):

mkdir my-deeptutor
cd my-deeptutor
pip install -U deeptutor

macOS / Linux:

mkdir -p my-deeptutor && cd my-deeptutor
pip install -U deeptutor

What success looks like: many packages download over a few minutes, ending with a line containing "Successfully installed".

Step 3 (Route A): First-time setup

deeptutor init

It asks, in order, for the backend port (default 8001), the frontend port (default 3782), the model provider, its Base URL, the API key and the model name. Then it offers an embedding provider and a web search provider; both can be skipped.

What success looks like: the command ends without errors and a data subfolder appears.

Note: You can skip this step for a quick look. The app still starts on the default ports but with no model configured. You can set that up later in Settings.

Step 4 (Route A): Start it

deeptutor start

What success looks like: the terminal prints the address of the interface, by default http://127.0.0.1:3782. Leave that window open. To stop the app, press Ctrl+C in it.

Route B: Run with Docker

If Docker Desktop is installed and running, one command is enough:

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

What success looks like: Docker downloads the image and prints startup logs. Open http://127.0.0.1:3782 in your browser. Settings, API keys, logs and knowledge bases are kept in a data volume named deeptutor-data, so they survive a restart.

With Route B you do not run deeptutor init. You configure the model in the Settings page of the web interface.

4. First use

1. Open a browser and go to http://127.0.0.1:3782.
2. If no model is configured yet: open Settings → Providers, enter a Base URL and API key and save. Then go to Language models, add a model and select it.
3. Go back to Chat and ask something, for example: "Explain the Fourier transform to a high-school student".

What the result looks like: the answer streams into the chat panel line by line. If that happens, the model connection works.

Things worth trying next:

• Task Board: a study tracker with To do, In progress and Done columns. It needs no model configuration.
• Knowledge Base: upload your own documents and ask questions about them. Requires an embedding model in Settings.
• Quiz: generate a quiz from a topic or a document.
• Video learning: paste a YouTube link to watch with captions and ask about specific timestamps.

The interface comes in several languages; switch in Settings. See the list inside the app.

5. Common problems and fixes

Symptom	Cause	Fix
Typing pip or deeptutor gives "command not found" or "is not recognized"	Python is not on PATH (the list of places your system looks for commands), or the terminal was not reopened after installing.	Close and reopen the terminal. On Windows, reinstall Python with "Add python.exe to PATH" ticked. You can also try python -m pip install -U deeptutor.
deeptutor start runs the backend but the interface never appears	Node.js is missing or older than 20. The web interface is served by Node.js.	Install Node.js 20 or newer, reopen the terminal and run deeptutor start again.
A port-in-use error, or 127.0.0.1:3782 will not open	Another program is using port 3782 or 8001.	Run deeptutor init again and choose other ports. With Docker, change the left-hand number in -p, for example -p 127.0.0.1:8088:3782, then open http://127.0.0.1:8088.
The app opens but chat never answers	No model configured, or the API key is wrong.	Check Base URL and API key in Settings → Providers, then select a model under Language models.
You put the key in a .env file and nothing changed	DeepTutor does not read a project-root .env as configuration.	Enter the key in the Settings page. The real settings live in data/user/settings/.
With Docker, Ollama on localhost cannot be reached	Inside Docker, localhost is the container itself, not your computer.	In Settings → Providers, use http://host.docker.internal:11434/v1 for Ollama. On Linux, add --add-host=host.docker.internal:host-gateway to the docker run command.
All settings seem gone after reopening	You ran deeptutor start from a different folder than last time.	Always cd into the folder from Step 2 before starting.

6. Uninstalling and updating

Updating (Route A). Stop the app with Ctrl+C, then rerun the install command with -U:

pip install -U deeptutor

Updating (Route B). Stop the running container, pull the new image, then rerun the Route B command:

docker pull ghcr.io/hkuds/deeptutor:latest

The latest version when this guide was written is v1.6.12 (released 27 September 2026). The project releases very often, every few days.

Uninstalling. The project describes removal in three separate parts:

1. Stop the app: press Ctrl+C in the terminal running deeptutor start.
2. Remove the data, only if you want everything gone: settings, API keys, chat history, memory, notebooks, knowledge bases. It all lives in the data folder inside the folder you made in Step 2. At startup, the line beginning with Workspace: shows the exact path. Back it up if you may need it, then move that folder to the Trash or Recycle Bin.
3. Remove the package:

python -m pip uninstall deeptutor

For Docker, remove the container and the volume. The second command permanently erases all data:

docker rm -f deeptutor
docker volume rm deeptutor-data

Note: If you pointed the "Content Workspace" at another folder in Settings, that folder is not removed by uninstalling. Back it up or delete it separately.

7. Frequently asked questions

Does it cost money? DeepTutor is free. Any cost is what you pay your AI model provider for usage. If you run a model locally (for example through Ollama), there is no API fee.

Does it need internet? You need internet to install and to call a model over an API. Video learning and web search always need it.

Where does my data live? Settings, API keys, chat history and knowledge bases are stored on your computer, in the data folder. However, your questions and the relevant passages of your documents are sent to whichever model provider you chose in order to get an answer.

Will it run on a weak computer? The project docs give no minimum spec. When you use a model through an API, the heavy computation happens on the provider's servers. When you run a model locally, your machine must be strong enough for that model.

Which languages are supported? You can ask in any language your chosen model understands. For the interface language, check the list in Settings of the version you installed.