How to Deploy GPT Academic with Docker: Complete Guide to Containerized AI Research

Deploy GPT Academic with Docker by using the pre-built images from GitHub Container Registry via docker-compose.yml, or build a lightweight online-only image from the Dockerfile, then configure API keys and ports through environment variables.

The binary-husky/gpt_academic repository provides a Python and Gradio-based web application for academic paper translation, analysis, and coding assistance. When you deploy GPT Academic with Docker, you isolate all dependencies—including the Python 3.12 interpreter, native tools like FFmpeg for text-to-speech, and optional CUDA libraries for local models—inside a portable container.

Understanding the Docker Architecture

The repository ships two primary containerization artifacts in the root directory. The Dockerfile builds a minimal online-only image using ghcr.io/astral-sh/uv:python3.12-bookworm as the base, installs dependencies via uv pip install -r requirements.txt, and executes python main.py. The [docker-compose.yml](https://github.com/binary-husky/gpt_academic/blob/master/docker-compose.yml) provides pre-built images for five distinct deployment scenarios (labeled 方案零 through 方案五), each targeting different capabilities such as cloud-only APIs, local LLM inference, LaTeX processing, or voice assistance.

Deployment Method 1: Using Pre-built Images with Docker Compose (Recommended)

The fastest way to deploy GPT Academic with Docker is to leverage the pre-built images hosted on GitHub Container Registry. These images eliminate build time and include pre-compiled binaries for specific use cases.

Choosing the Right Deployment Scheme (方案)

The docker-compose.yml defines five schemes (方案). Keep only the block matching your requirements and delete the others before starting the container:

• 方案一 (No Local LLMs): Use ghcr.io/binary-husky/gpt_academic_nolocal:master when you only need cloud APIs like ChatGPT, Claude, or Azure. This is the smallest image and fastest to pull.
• 方案二 (Local Models): Use ghcr.io/binary-husky/gpt_academic_chatglm_moss:master to run quantized Chinese models (ChatGLM, Qwen, MOSS) locally. Requires NVIDIA GPU support.
• 方案三 (Jittor Models): Use ghcr.io/binary-husky/gpt_academic_jittorllms:master for RWKV, LLaMA, or Pangu models built on the Jittor framework.
• 方案四 (LaTeX Support): Use ghcr.io/binary-husky/gpt_academic_with_latex:master when processing PDF academic papers that require LaTeX compilation.
• 方案五 (Audio Assistant): Use ghcr.io/binary-husky/gpt_academic_audio_assistant:master for real-time voice input/output capabilities; includes FFmpeg binaries.

Each scheme maps an image to an environment: block where you inject API keys, model selections, and UI preferences.

Configuring the Container Environment

All runtime settings are read by config.py according to this precedence: environment variables (highest), config_private.py (if mounted), then config.py defaults. Essential variables to set in your chosen compose block include:

Variable	Purpose
API_KEY	OpenAI, Azure, Baidu, or other provider credentials.
LLM_MODEL	Default model (e.g., gpt-3.5-turbo, chatglm).
AVAIL_LLM_MODELS	JSON array of models available in the UI dropdown.
WEB_PORT	Port for the Gradio server (must match Docker expose settings).
THEME	UI theme such as Chuanhu-Small-and-Beautiful or dark.
LOCAL_MODEL_DEVICE	Set to cuda or cpu when using local model images.

Network and Port Exposure

You must choose between host networking and port mapping based on your operating system:

• Linux (Host Networking): Keep network_mode: "host" in the compose file. The container binds directly to the host stack, and you access the UI at http://localhost:<WEB_PORT>.
• Cross-Platform (Port Mapping): Remove network_mode and uncomment the ports: block to map container ports explicitly:

ports:
  - "12345:12345"

Enabling GPU Support for Local Models

For 方案二 or 方案三, add the NVIDIA runtime to expose your GPU:

runtime: nvidia
devices:
  - /dev/nvidia0:/dev/nvidia0

Ensure LOCAL_MODEL_DEVICE is set to cuda in the environment section.

Deployment Method 2: Building the Minimal Online-Only Image

If you prefer to build from source or need a custom image, use the repository's Dockerfile. This creates a lightweight container without local LLM binaries or LaTeX toolchains.

Building from the Dockerfile

The build process uses a multi-stage approach with uv for fast dependency resolution:

docker build -t gpt-academic .

The Dockerfile performs these steps:

1. Sets WORKDIR /gpt for all subsequent operations.
2. Copies requirements.txt and creates a Python 3.12 virtual environment using uv venv.
3. Installs dependencies via uv pip install -r requirements.txt.
4. Copies the entire source tree with COPY . ..
5. Pre-warms modules by running python -c "from check_proxy import warm_up_modules; warm_up_modules()".
6. Exposes the entry point as CMD ["bash", "-c", "python main.py"].

Running the Built Container

Execute your custom image with environment variables injected at runtime:

docker run -d \
  -e API_KEY="sk-your-key-here" \
  -e LLM_MODEL="gpt-4" \
  -e WEB_PORT="8080" \
  -p 8080:8080 \
  gpt-academic

The container executes main.py, which launches the Gradio interface and loads all plugins. Once the warm-up step completes, the web UI becomes interactive at http://localhost:8080.

Step-by-Step Deployment Commands

Follow these commands to deploy GPT Academic with Docker using the recommended pre-built approach:

1. Clone the repository and navigate to the directory:

git clone https://github.com/binary-husky/gpt_academic.git
cd gpt_academic

2. Edit docker-compose.yml—delete all service blocks except your chosen scheme (e.g., gpt_academic_nolocalllms for cloud-only usage).

3. Configure your API keys and preferences in the environment: section of the remaining service block.

4. Start the container in detached mode:

docker-compose up -d

5. Access the interface at http://localhost:12345 (or your configured WEB_PORT).

To view logs during startup:

docker-compose logs -f

To stop the service:

docker-compose down

Summary

• Use pre-built images via docker-compose.yml for fastest deployment; choose 方案一 for cloud APIs only, or 方案二 through 方案五 for local models, LaTeX, or audio capabilities.
• Set configuration through environment variables in the compose file, which override config.py defaults; key variables include API_KEY, LLM_MODEL, and WEB_PORT.
• Enable GPU access by adding runtime: nvidia and device mappings when deploying local model schemes.
• Expose the UI using network_mode: "host" on Linux or explicit ports: mapping for cross-platform compatibility.
• Build custom images from the Dockerfile only if you need a minimal online-only deployment or custom modifications to the base environment.

Frequently Asked Questions

Do I need to build the Docker image myself?

No. The binary-husky/gpt_academic repository provides pre-built images on GitHub Container Registry for all common use cases. You only need to build from the Dockerfile if you require a custom online-only image or want to modify the base environment. The pre-built images include all necessary dependencies for LaTeX processing, local LLMs, or audio features.

How do I switch between cloud APIs and local models?

Edit the docker-compose.yml file to select a different scheme (方案). For cloud-only access, use 方案一 with the image ghcr.io/binary-husky/gpt_academic_nolocal:master. For local models like ChatGLM or Qwen, switch to 方案二 and set AVAIL_LLM_MODELS to include "chatglm" or "qwen". Ensure you configure LOCAL_MODEL_DEVICE to cuda and enable the NVIDIA runtime when using local models.

Why is my container not detecting the GPU?

GPU support requires three specific configurations in your docker-compose.yml: set runtime: nvidia, map the GPU device under devices: (e.g., /dev/nvidia0:/dev/nvidia0), and ensure LOCAL_MODEL_DEVICE is set to cuda in the environment variables. Additionally, your Docker host must have the NVIDIA Container Toolkit installed and the nvidia runtime configured in /etc/docker/daemon.json.

Can I run GPT Academic on Windows with Docker?

Yes. For Windows deployment, remove or comment out network_mode: "host" (which is Linux-only) and use the ports: mapping instead. Expose the port explicitly by mapping your configured WEB_PORT (e.g., "12345:12345"). The pre-built images work on Windows Docker Desktop, though GPU passthrough for local models requires Windows Subsystem for Linux 2 (WSL2) backend with NVIDIA support enabled.

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