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

> Easily deploy GPT Academic with Docker using pre-built images or build your own. Configure API keys and ports via environment variables for containerized AI research.

- Repository: [binary-husky/gpt_academic](https://github.com/binary-husky/gpt_academic)
- Tags: how-to-guide
- Published: 2026-03-02

---

**Deploy GPT Academic with Docker by using the pre-built images from GitHub Container Registry via [`docker-compose.yml`](https://github.com/binary-husky/gpt_academic/blob/main/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`](https://github.com/binary-husky/gpt_academic/blob/master/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/main/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`](https://github.com/binary-husky/gpt_academic/blob/main/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`](https://github.com/binary-husky/gpt_academic/blob/main/config.py)** according to this precedence: environment variables (highest), [`config_private.py`](https://github.com/binary-husky/gpt_academic/blob/main/config_private.py) (if mounted), then [`config.py`](https://github.com/binary-husky/gpt_academic/blob/main/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:

```yaml
ports:
  - "12345:12345"

```

### Enabling GPU Support for Local Models

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

```yaml
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`](https://github.com/binary-husky/gpt_academic/blob/master/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:

```bash
docker build -t gpt-academic .

```

The Dockerfile performs these steps:
1. Sets `WORKDIR /gpt` for all subsequent operations.
2. Copies [`requirements.txt`](https://github.com/binary-husky/gpt_academic/blob/main/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:

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

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

```

2. Edit [`docker-compose.yml`](https://github.com/binary-husky/gpt_academic/blob/main/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:

```bash
docker-compose up -d

```

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

To view logs during startup:

```bash
docker-compose logs -f

```

To stop the service:

```bash
docker-compose down

```

## Summary

- **Use pre-built images** via [`docker-compose.yml`](https://github.com/binary-husky/gpt_academic/blob/main/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`](https://github.com/binary-husky/gpt_academic/blob/main/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`](https://github.com/binary-husky/gpt_academic/blob/main/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`](https://github.com/binary-husky/gpt_academic/blob/main/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`](https://github.com/binary-husky/gpt_academic/blob/main//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.