Self-Hosting Kiwix with Docker Compose

What Is Kiwix?

Kiwix is a self-hosted offline content server that lets you browse entire websites — Wikipedia, Arch Wiki, Stack Exchange, Project Gutenberg, TED Talks, and thousands more — without an internet connection. It serves pre-built ZIM archives over HTTP, giving anyone on your network access to a massive offline library. Kiwix powers offline education in schools, libraries, and disaster relief operations worldwide.

Official site: kiwix.org | GitHub

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended)
• Docker and Docker Compose installed (guide)
• At least 1 GB of free disk space for the app itself, plus storage for ZIM files (Wikipedia alone is 100+ GB)
• 256 MB of RAM minimum

Download ZIM Files First

Kiwix serves pre-built ZIM archives. You need to download at least one before starting.

Browse the full library at download.kiwix.org/zim/. Here are the most popular:

Content	File	Size
Wikipedia (English, full)	wikipedia_en_all_maxi.zim	~100 GB
Wikipedia (English, no images)	wikipedia_en_all_nopic.zim	~12 GB
Wikipedia (Simple English)	wikipedia_en_simple_all.zim	~600 MB
Arch Wiki	archlinux.zim	~800 MB
Stack Exchange (all sites)	stackexchange.zim	~90 GB
Project Gutenberg	gutenberg.zim	~70 GB
TED Talks	ted_en.zim	~30 GB
WikiHow (English)	wikihow_en.zim	~10 GB

Download a ZIM file to your server:

mkdir -p /opt/kiwix/data
cd /opt/kiwix/data
wget https://download.kiwix.org/zim/wikipedia/wikipedia_en_simple_all_maxi_2025-01.zim

Start with Simple English Wikipedia (~600 MB) to test, then add larger archives as needed.

Docker Compose Configuration

Create a docker-compose.yml file:

# /opt/kiwix/docker-compose.yml
services:
  kiwix:
    image: ghcr.io/kiwix/kiwix-tools:3.8.2
    container_name: kiwix
    command: kiwix-serve --port 8080 --library /data/*.zim
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./data:/data:ro    # ZIM files directory (read-only)

Start the container:

docker compose up -d

Access the library at http://your-server-ip:8080.

Serving Multiple ZIM Files

The glob pattern *.zim serves all ZIM files in the /data directory. Add new ZIM files to the data/ folder and restart:

docker compose restart kiwix

For a curated library with specific files:

services:
  kiwix:
    image: ghcr.io/kiwix/kiwix-tools:3.8.2
    container_name: kiwix
    command: >
      kiwix-serve --port 8080
      /data/wikipedia_en_simple_all_maxi_2025-01.zim
      /data/archlinux.zim
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./data:/data:ro

Configuration Options

Kiwix-serve accepts command-line flags:

Flag	Default	Description
--port	80	HTTP listening port
--address	0.0.0.0	Bind address
--threads	4	Number of server threads
--verbose	off	Enable verbose logging
--nodatealiases	off	Disable date-based URL aliases
--blockexternal	off	Block external links in served content

For a server behind a reverse proxy, set --address 0.0.0.0 and let the proxy handle SSL.

Reverse Proxy

For HTTPS access with a custom domain:

Nginx Proxy Manager: Add a proxy host pointing to kiwix:8080. See Nginx Proxy Manager setup.

Caddy:

wiki.example.com {
    reverse_proxy kiwix:8080
}

See Caddy Reverse Proxy Setup.

Keeping ZIM Files Updated

ZIM files are rebuilt periodically (usually monthly for major wikis). To update:

1. Download the new ZIM file to your data directory
2. Remove the old version
3. Restart Kiwix: docker compose restart kiwix

Automate with a cron job:

# /etc/cron.monthly/update-kiwix
#!/bin/bash
cd /opt/kiwix/data
# Download latest Simple English Wikipedia
wget -N https://download.kiwix.org/zim/wikipedia/wikipedia_en_simple_all_maxi_2025-01.zim
docker compose -f /opt/kiwix/docker-compose.yml restart kiwix

Backup

ZIM files are static downloads — you don’t need to back them up. Just re-download if lost. Back up your docker-compose.yml only.

See Backup Strategy.

Troubleshooting

Kiwix shows “No content available”

Symptom: The web UI loads but shows no libraries. Fix: Verify ZIM files exist in the mounted data directory and are not corrupted. Check the command includes the correct path to your ZIM files. Run docker logs kiwix to see if files are being detected.

High memory usage with large ZIM files

Symptom: Container memory usage spikes when serving full English Wikipedia. Fix: This is expected — Kiwix memory-maps ZIM files for performance. The OS manages the memory-mapped region efficiently. Actual RSS usage stays low (256–512 MB). The reported memory includes the mapped file size, which isn’t real RAM consumption.

Slow initial page loads

Symptom: First request after restart takes several seconds. Fix: Kiwix indexes ZIM files on startup. Larger files take longer. For very large libraries (500+ GB), increase --threads to 8 and ensure storage is SSD-backed.

Resource Requirements

• RAM: 128–256 MB idle, 256–512 MB under load (excludes memory-mapped files)
• CPU: Very low — serves static content
• Disk: Depends entirely on ZIM file selection. Simple English Wikipedia: 600 MB. Full English Wikipedia: 100+ GB.
• Network: Minimal — all content served locally

Verdict

Kiwix is the simplest way to host massive reference libraries offline. Wikipedia, Arch Wiki, Stack Exchange, and thousands of other sites — all served from a single lightweight container with zero external dependencies. It’s not a web archiver (use ArchiveBox for saving arbitrary web pages), but for serving pre-built offline libraries, nothing else comes close.

Run it on a Raspberry Pi for a family reference library, or on a home server alongside your other self-hosted services. The 128 MB RAM footprint means it fits anywhere.

Related

• Self-Hosting ArchiveBox
• ArchiveBox vs Kiwix
• Best Self-Hosted Archiving Tools
• Docker Compose Basics
• Reverse Proxy Setup
• Backup Strategy
• Best Hardware for Home Servers