Requirements for Running DeepTutor: Complete Setup Guide

To run DeepTutor, you need Python 3.11+, Node.js for the web interface, and properly configured environment variables for LLM and embedding providers as defined in the .env.example file.

Setting up HKUDS/DeepTutor requires specific software dependencies and API configurations to enable its AI tutoring capabilities. Understanding the requirements for running DeepTutor ensures a smooth deployment whether you choose the guided installer, manual setup, or Docker containerization. This guide covers the mandatory system prerequisites, environment variables, and installation methods based on the official source code.

Core System Requirements

Python and Node.js Dependencies

DeepTutor requires Python 3.11 or later as the foundation for its backend services. According to the README.md, the project is built specifically for Python 3.11+ and will not run on earlier versions. For the Next.js web UI, you also need a recent LTS version of Node.js with npm installed.

The Python dependencies are split between two requirement files:

• requirements/cli.txt – Minimal dependencies for command-line usage
• requirements/server.txt – Full backend stack including FastAPI and optional extras

Operating System Compatibility

DeepTutor supports Linux, macOS, and Windows for native installation. However, if you deploy using Docker containers, note that the Docker images are Linux-only as specified in the Dockerfile header. For Windows users, WSL2 is recommended for the most consistent experience with the Linux-based containers.

Hardware Specifications

No special GPU is required for core DeepTutor features. A GPU becomes necessary only if you intend to run an OpenAI-compatible local model via Ollama or vLLM rather than using cloud-based API providers.

Mandatory Environment Configuration

Before running DeepTutor, you must create a .env file from the provided .env.example template. This configuration file stores credentials for your chosen AI providers.

LLM Provider Variables

You must configure at least one large language model provider by setting these variables in your .env file:

• LLM_BINDING – The provider type (OpenAI, Anthropic, Ollama, etc.)
• LLM_MODEL – Specific model identifier
• LLM_API_KEY – Your API key for the provider
• LLM_HOST – Base URL for the API endpoint

DeepTutor supports multiple providers including OpenAI, Anthropic, and local Ollama instances as documented in the README's provider tables.

Embedding Provider Variables

Similar to LLM configuration, you must set embedding provider variables:

• EMBEDDING_BINDING – Provider type for embeddings
• EMBEDDING_MODEL – Model identifier for vector generation
• EMBEDDING_API_KEY – API authentication key
• EMBEDDING_HOST – API endpoint URL
• EMBEDDING_DIMENSION – Vector dimension size for your chosen model

Optional Web Search Integration

If you plan to use the web_search tool, configure these additional variables:

• SEARCH_PROVIDER – Choose from Brave, Tavily, or other supported providers
• SEARCH_API_KEY – Authentication key for your chosen search service

Installation Methods

DeepTutor offers four distinct installation paths to accommodate different deployment scenarios.

Option A: Guided Tour (Recommended)

The interactive installer automates dependency installation and environment setup:

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

# Create Python environment

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

# Launch interactive installer

python scripts/start_tour.py

The scripts/start_tour.py script walks you through creating the .env file, installing dependencies, and launching both the backend and frontend automatically.

Option B: Manual Local Installation

For users who prefer direct control over the setup process:

# Clone repository

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

# Setup Python environment

conda create -n deeptutor python=3.11 && conda activate deeptutor
pip install -e ".[server]"

# Install frontend dependencies

cd web && npm install && cd ..

# Configure environment

cp .env.example .env

# Edit .env to set LLM_*, EMBEDDING_*, and optional SEARCH_* variables

Option C: Docker Deployment

Deploy without installing Python or Node.js locally using Docker Compose:

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

# Setup environment file

cp .env.example .env

# Edit .env with your API credentials

# Run pre-built image from GitHub Container Registry

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

# Or build from source

docker compose up -d

After startup, access the Web UI at http://localhost:3782 and the Backend API at http://localhost:8001.

Option D: CLI-Only Mode

Run DeepTutor without the web interface for terminal-based usage:

pip install -e ".[cli]"

# Interactive REPL

deeptutor chat

# Single command execution

deeptutor run chat "Explain Fourier transform"

# Knowledge base management

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

The CLI entry point is defined in deeptutor_cli/main.py, providing full functionality without the Next.js frontend.

Key Source Files and Their Roles

Understanding these critical files helps with troubleshooting and customization:

• .env.example – Template containing all required and optional environment variables
• requirements/cli.txt – Python dependencies for terminal-only usage
• requirements/server.txt – Complete backend dependencies including FastAPI
• docker-compose.yml – Service definitions for building from source
• docker-compose.ghcr.yml – Service definitions using pre-built GitHub Container Registry images
• scripts/start_tour.py – Interactive installation wizard used in Option A
• Dockerfile – Container build instructions defining the base image and build steps
• deeptutor_cli/main.py – Entry point for the deeptutor command-line interface

Summary

• Python 3.11+ and Node.js are mandatory prerequisites, with dependencies defined in requirements/server.txt and the web/ directory respectively
• You must create a .env file from .env.example containing valid LLM and Embedding provider credentials before starting the application
• Four installation methods are available: guided tour (scripts/start_tour.py), manual local setup, Docker deployment (docker-compose.ghcr.yml), and CLI-only mode
• No GPU is required unless running local models via Ollama or vLLM
• The web interface runs on port 3782 while the API server listens on port 8001 in Docker deployments

Frequently Asked Questions

What Python version is required for DeepTutor?

DeepTutor requires Python 3.11 or later. The project is specifically built for Python 3.11, and earlier versions are not supported. This requirement is enforced in the installation documentation and the conda create commands used in the setup scripts.

Do I need a GPU to run DeepTutor?

No GPU is required for the core features of DeepTutor when using cloud-based LLM providers like OpenAI or Anthropic. A GPU becomes necessary only if you choose to run local models through Ollama or vLLM, as these perform inference on your local hardware rather than via API calls.

Can I run DeepTutor without the web interface?

Yes, DeepTutor supports a CLI-only mode that eliminates the Node.js requirement. Install using pip install -e ".[cli]" and use the deeptutor command to access the interactive chat interface and knowledge base management tools directly from your terminal without launching the Next.js frontend.

Where do I configure my LLM API keys?

All API keys and provider settings are configured in the .env file at the project root. Copy the provided .env.example template and fill in the required variables including LLM_API_KEY, LLM_BINDING, EMBEDDING_API_KEY, and EMBEDDING_BINDING. DeepTutor will not start without these environment variables properly set.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}