# Requirements for Running DeepTutor: Complete Setup Guide

> Discover the requirements for running DeepTutor. Learn about Python 3.11+, Node.js, and environment variable setup for LLM providers. Get your complete setup guide now.

- Repository: [✨Data Intelligence Lab@HKU✨/DeepTutor](https://github.com/HKUDS/DeepTutor)
- Tags: getting-started
- Published: 2026-04-08

---

**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`](https://github.com/HKUDS/DeepTutor/blob/main/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`](https://github.com/HKUDS/DeepTutor/blob/main/requirements/cli.txt)** – Minimal dependencies for command-line usage
- **[`requirements/server.txt`](https://github.com/HKUDS/DeepTutor/blob/main/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:

```bash
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`](https://github.com/HKUDS/DeepTutor/blob/main/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:

```bash

# 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:

```bash
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:

```bash
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`](https://github.com/HKUDS/DeepTutor/blob/main/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`](https://github.com/HKUDS/DeepTutor/blob/main/requirements/cli.txt)** – Python dependencies for terminal-only usage
- **[`requirements/server.txt`](https://github.com/HKUDS/DeepTutor/blob/main/requirements/server.txt)** – Complete backend dependencies including FastAPI
- **[`docker-compose.yml`](https://github.com/HKUDS/DeepTutor/blob/main/docker-compose.yml)** – Service definitions for building from source
- **[`docker-compose.ghcr.yml`](https://github.com/HKUDS/DeepTutor/blob/main/docker-compose.ghcr.yml)** – Service definitions using pre-built GitHub Container Registry images
- **[`scripts/start_tour.py`](https://github.com/HKUDS/DeepTutor/blob/main/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`](https://github.com/HKUDS/DeepTutor/blob/main/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`](https://github.com/HKUDS/DeepTutor/blob/main/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`](https://github.com/HKUDS/DeepTutor/blob/main/scripts/start_tour.py)), manual local setup, Docker deployment ([`docker-compose.ghcr.yml`](https://github.com/HKUDS/DeepTutor/blob/main/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.