Wan2GP on Ubuntu: Docker and Manual Installation

Overview

Wan2GP, now commonly branded in the repository as WanGP, is an open-source web interface for running image, video, and audio generation models such as Wan, Hunyuan, SkyReel, LTX, VACE, and related workflows. Its appeal is that it focuses on practical local generation, quantized model support, low-VRAM operation, LoRAs, prompt helpers, video tooling, and a browser-based UI.

Best recommendation: On Ubuntu with an NVIDIA GPU, start with the repository’s Docker script. It is designed to detect your GPU and VRAM, configure the NVIDIA Docker runtime if needed, build the right image, and preserve downloaded models and generated outputs on your host machine.

Use Docker if…

You want the most repeatable setup.
You want CUDA/PyTorch dependencies isolated.
You are not already managing a custom Python/conda AI stack.

→

Use manual install if…

You understand Python environments and PyTorch CUDA wheels.
You need to debug or modify dependencies directly.
You are comfortable matching Python, Torch, CUDA, and GPU generation.

Requirements

Hardware

NVIDIA GPU. The project advertises support for many generations, including RTX 40xx, 30xx, 20xx, GTX 16xx/10xx, Tesla V100, A100, H100, and more.
VRAM: 6GB can be enough for certain lower/quantized models, but 8–12GB+ is far more comfortable for video work.
Disk: plan for tens to hundreds of GB. Models, LoRAs, caches, and outputs grow quickly.
RAM: 16GB minimum practical; 32GB+ recommended for heavy workflows.

Software

Ubuntu 22.04 LTS or 24.04 LTS.
Official NVIDIA driver that works with your kernel.
Docker Engine plus NVIDIA Container Toolkit for the Docker path.
Git, Python/conda, ffmpeg, and build tools for manual path.
A network connection for cloning the repository and downloading models.

Important naming note: The provided source text mentions ./start.sh and python app.py. The current official repository README shows the Ubuntu/Debian Docker runner as ./run-docker-cuda-deb.sh and the app launch command as python wgp.py. Use the current repository scripts unless your local clone clearly documents a different wrapper.

Preflight Checks Before Installing

Run these checks first. They tell you whether the driver, GPU, and shell environment are ready.

# Confirm Ubuntu version
lsb_release -a

# Confirm GPU is visible
lspci | grep -i nvidia

# Confirm the NVIDIA driver is loaded and usable
nvidia-smi

# Confirm Git is available
git --version

Success check: nvidia-smi should print your GPU model, driver version, CUDA compatibility, memory usage, and running processes. If nvidia-smi fails, fix the NVIDIA driver before installing Wan2GP.

Install or repair NVIDIA drivers

Ubuntu recommends installing NVIDIA drivers through the package manager rather than random .run files. On a desktop/workstation Ubuntu install, this common sequence is usually enough:

sudo apt update
sudo ubuntu-drivers devices
sudo ubuntu-drivers install
sudo reboot
nvidia-smi

If you manage production/server GPUs, follow Ubuntu’s server driver guidance and choose the driver branch appropriate for your hardware and kernel.

Recommended Path: Docker Installation

The Docker path is easiest because it isolates the CUDA, PyTorch, SageAttention, and Python dependency stack from the rest of your system.

4.1 Install Docker Engine on Ubuntu

# Remove old/conflicting packages if present
for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do
  sudo apt-get remove -y "$pkg" 2>/dev/null || true
done

# Add Docker's official apt repository
sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

cat <


          Optional: let your user run Docker without typing sudo. Log out and back in after this, or run newgrp docker.
          sudo usermod -aG docker $USER
newgrp docker

          4.2 Install NVIDIA Container Toolkit
          This is the bridge that lets Docker containers access the host NVIDIA GPU.
          curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
  | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
  | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
  | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
          Verify GPU passthrough into a container:
          sudo docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi
          Success check: the Dockerized nvidia-smi command should show the same GPU information as host nvidia-smi.

          4.3 Clone Wan2GP
          mkdir -p ~/ai
cd ~/ai
git clone https://github.com/deepbeepmeep/Wan2GP.git
cd Wan2GP

          4.4 Run the official Ubuntu/Debian Docker script
          chmod +x ./run-docker-cuda-deb.sh
./run-docker-cuda-deb.sh
          According to the project README, this script is designed to:
          Detect your GPU model and VRAM.
Select an optimal CUDA architecture for your GPU.
Install or configure NVIDIA Docker runtime if needed.
Build a Docker image with CUDA, cuDNN, PyTorch, SageAttention, and performance environment variables.
Mount the current directory so models, LoRAs, generated videos, and downloaded files persist locally.
Start the WanGP web interface.
          First run can take a while: Docker may download base images, compile components, and install Python packages. Do not interrupt it unless it is clearly stuck on an error.



        
          5
Alternative Path: Manual Python Installation
          Use this path only if you want full control over the Python environment. The current repository README gives conda examples rather than a plain venv-first path because matching Python and PyTorch versions matters.
          5.1 Install system prerequisites
          sudo apt update
sudo apt install -y git ffmpeg python3 python3-venv python3-pip build-essential
          5.2 Clone the repository
          mkdir -p ~/ai
cd ~/ai
git clone https://github.com/deepbeepmeep/Wan2GP.git
cd Wan2GP
          5.3 Recommended manual path: conda / mamba
          The exact Python and PyTorch versions may change as the project evolves. Check the current README before running these. As of the researched README, the NVIDIA examples were:
          
            RTX 20xx–RTX 50xx style example
conda create -n wan2gp python=3.11.14
conda activate wan2gp
pip install torch==2.10.0 torchvision==0.25.0 torchaudio==2.10.0 \
  --index-url https://download.pytorch.org/whl/cu130
pip install -r requirements.txt
            GTX 10xx style example
conda create -n wan2gp python=3.10.9
conda activate wan2gp
pip install torch==2.7.1 torchvision==0.22.1 torchaudio==2.7.1 \
  --index-url https://download.pytorch.org/whl/test/cu128
pip install -r requirements.txt
          
          Do not blindly copy stale PyTorch commands. Use the project README and the PyTorch install selector to match your GPU generation, CUDA wheel, and Python version. If you see shape, CUDA, or missing symbol errors, suspect a version mismatch before blaming Wan2GP.
          5.4 Venv variant, if you do not use conda
          A venv can work, but you must choose a Python version and PyTorch wheel compatible with the current repository. This is a generic pattern, not a guarantee for every GPU:
          python3 -m venv wan2gp-env
source wan2gp-env/bin/activate
python -m pip install --upgrade pip wheel setuptools

# Example only: choose the current PyTorch command from https://pytorch.org/get-started/locally/
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
pip install -r requirements.txt
          5.5 Launch manually
          python wgp.py
        

        
          6
First Run: Open the Web Interface and Download Models
          After the Docker script or manual launch starts the app, look in the terminal output for the local URL. It is typically a local web address such as:
          http://127.0.0.1:7860
# or another printed localhost / LAN URL
          Open the URL in a browser on the same machine. If you are on a remote Ubuntu server, forward the port over SSH or launch the app with the documented host/listen option for your setup, then secure it appropriately.
          First-time model setup: The README recommends using the Guides tab inside WanGP to find recommended models. Some models auto-download when selected; others require you to place checkpoints, LoRAs, or related files in the expected folders.
          Practical first test
          Start with a small or quantized model recommended by the app for your VRAM.
Use a short prompt and a low frame count / short duration.
Generate one small sample before changing many settings.
Confirm the output file appears in the local project/output directory.
        

        
          7
Update and Maintenance
          Update the repository
          cd ~/ai/Wan2GP
git pull
          Docker path
          After pulling updates, rerun the Docker script. If dependencies changed, Docker may rebuild layers.
          ./run-docker-cuda-deb.sh
          Manual path
          Stay in your chosen environment and reinstall requirements if needed:
          cd ~/ai/Wan2GP
conda activate wan2gp   # or source wan2gp-env/bin/activate
pip install -r requirements.txt
python wgp.py
          Before major updates: Save your working configuration, note your current commit with git rev-parse --short HEAD, and keep a copy of important outputs/models. AI tool repos can move quickly.
        

        
          8
Verification Checklist
          nvidia-smi works on the host.
docker run --gpus all ... nvidia-smi works if using Docker.
The Wan2GP repository is cloned and current.
The Docker script completes without a Python traceback, CUDA error, or missing package error.
The terminal prints a local web interface URL.
The web UI opens in a browser.
A small test generation completes and writes an output file.
GPU memory usage increases during generation, visible in nvidia-smi.
          # Watch GPU usage during generation
watch -n 1 nvidia-smi
        

        
          9
Troubleshooting
          
            Symptom Likely cause Fix
            
              nvidia-smi fails on host NVIDIA driver not installed, wrong kernel module, or driver/library mismatch. Install via ubuntu-drivers install, reboot, and retest. If mismatch persists after upgrades, reboot first; then reinstall matching driver packages.
              Docker works, but container cannot see GPU NVIDIA Container Toolkit missing or Docker runtime not configured. Install nvidia-container-toolkit, run sudo nvidia-ctk runtime configure --runtime=docker, restart Docker, and verify with Dockerized nvidia-smi.
              permission denied when running Docker User is not in the Docker group. Use sudo docker ... or run sudo usermod -aG docker $USER, then log out/in or run newgrp docker.
              Out of memory / CUDA OOM Model or settings exceed VRAM. Use lower-VRAM/quantized models, lower resolution, shorter duration, fewer frames, fewer simultaneous generations, or close other GPU apps.
              Manual install imports fail Wrong Python, PyTorch, CUDA wheel, or missing system library. Prefer Docker. If manual, recreate the environment using the exact current README commands for your GPU generation.
              Web page never opens App failed during startup, wrong port, or remote server networking. Read the terminal log for the actual URL and error. On a remote machine, use SSH port forwarding: ssh -L 7860:127.0.0.1:7860 user@server.
              Very slow first generation Model download, shader/kernel compile, or cold cache. Wait for the first run to finish. Subsequent runs are usually faster after caches and models are local.
              Generated outputs disappear after container restart Container paths not mounted to host or running from unexpected directory. Run the official Docker script from the Wan2GP repository directory so its local mount behavior preserves models and outputs.
            
          
          Security note: Do not expose the Wan2GP web UI directly to the public internet without authentication, firewall rules, or a secure tunnel. Treat local generation interfaces as powerful local tools, not public web apps.
        

        
          10
Sources and References
          
            Wan2GP GitHub repository — official project README, Docker runner, manual install examples, feature list, launch/update notes.
            Docker Engine on Ubuntu — official Docker apt repository installation and verification.
            NVIDIA Container Toolkit install guide — Docker runtime configuration for GPU passthrough.
            Ubuntu NVIDIA drivers documentation — package-manager driver installation and troubleshooting guidance.
            PyTorch local install selector — choose current PyTorch wheel commands for CUDA/manual installs.
          
          This guide corrects a few likely stale commands in the supplied source text: current repository guidance uses ./run-docker-cuda-deb.sh for Ubuntu/Debian Docker installs and python wgp.py for manual launch.

Symptom	Likely cause	Fix
`nvidia-smi` fails on host	NVIDIA driver not installed, wrong kernel module, or driver/library mismatch.	Install via `ubuntu-drivers install`, reboot, and retest. If mismatch persists after upgrades, reboot first; then reinstall matching driver packages.
Docker works, but container cannot see GPU	NVIDIA Container Toolkit missing or Docker runtime not configured.	Install `nvidia-container-toolkit`, run `sudo nvidia-ctk runtime configure --runtime=docker`, restart Docker, and verify with Dockerized `nvidia-smi`.
`permission denied` when running Docker	User is not in the Docker group.	Use `sudo docker ...` or run `sudo usermod -aG docker $USER`, then log out/in or run `newgrp docker`.
Out of memory / CUDA OOM	Model or settings exceed VRAM.	Use lower-VRAM/quantized models, lower resolution, shorter duration, fewer frames, fewer simultaneous generations, or close other GPU apps.
Manual install imports fail	Wrong Python, PyTorch, CUDA wheel, or missing system library.	Prefer Docker. If manual, recreate the environment using the exact current README commands for your GPU generation.
Web page never opens	App failed during startup, wrong port, or remote server networking.	Read the terminal log for the actual URL and error. On a remote machine, use SSH port forwarding: `ssh -L 7860:127.0.0.1:7860 user@server`.
Very slow first generation	Model download, shader/kernel compile, or cold cache.	Wait for the first run to finish. Subsequent runs are usually faster after caches and models are local.
Generated outputs disappear after container restart	Container paths not mounted to host or running from unexpected directory.	Run the official Docker script from the Wan2GP repository directory so its local mount behavior preserves models and outputs.