Zimi

A modern experience for your ZIM files.

Kiwix packages the world's knowledge into ZIM files. Zimi makes them feel like the real internet with a rich web UI, fast JSON API, and an MCP server for AI agents. Everything works offline, in your language.

What is Zimi?

• The offline internet. Entire websites, cross-ZIM linking, search engine and native browser experience.
• Search that hits everything. One query, every source, 100M+ articles, the right answer on top. Fast.
• Multilingual. Switch any article into any language it has. Ten UI languages built in.
• A real library. 1,000+ archives one click away, auto-updates, collections, batch downloads, bookmarks and history.
• Your own network. Your machines find each other and pass ZIMs around at LAN speed, no internet needed.
• A good citizen. Downloads arrive over BitTorrent and seed back to the Kiwix network. One switch makes you a full mirror.
• Fresh daily. Picture of the Day, On This Day, a word, a quote, a comic, a live almanac sky. All computed locally, forever.
• Accessible. If you browse by keyboard, listen by screen reader, or need high contrast, accessibility is built-in.
• Anywhere. Docker, pip, a native macOS app, or your phone as a PWA.
• Improving. Regular updates with ideas from the community, GitHub and creator keep Zimi fresh. Just ask!
• For humans and machines. Web UI, JSON API, MCP server for AI agents.

Screenshots

Homepage	Search Results

Language Switching	Catalog

Sharing

Languages

Not an afterthought. Language is deeply integrated into every aspect of Zimi so you can focus on your content and feel at home. Enjoy filtered lists, labeled sources, RTL support and no rock left unturned.

• 10 languages. English, French, German, Spanish, Portuguese, Russian, Chinese, Arabic, Hindi, Hebrew.

Something not right? Open an issue. Found a security problem? See SECURITY.md — report it privately.

Sharing

Three switches in Server Settings control all of it:

• BitTorrent (on by default). Downloads arrive via the Kiwix swarm and seed back, capped at a ratio you choose. 0 means never seed. The Mac and Linux desktop apps and the Docker image ship their own BitTorrent engine (in-process libtorrent); a bare pip install uses it if the wheel is present — and everything quietly falls back to plain HTTP without it. UPnP asks your router to open the port, and the settings panel shows whether it worked.
• Nearby (off by default). Flip it on and Zimi devices on your network find each other; a green pill on a catalog card means a neighbor already has that ZIM. Transfers stay on your LAN, never the internet.
• Mirror (off). Lifts the seeding cap, for people who want to run a long-term Kiwix mirror.

Seeding needs no router setup: Zimi opens the BitTorrent port automatically (UPnP) and the settings show whether peers can reach you, with a retry when they can't. DHT is on too, so magnet links and trackerless swarms just work.

Install

macOS

brew tap epheterson/zimi && brew install --cask zimi

Or download from GitHub Releases.

Linux

sudo snap install zimi

Or grab the AppImage.

Docker

docker run --network host -v ./zims:/zims -v ./zimi-config:/config epheterson/zimi

/zims is where ZIM files live. /config persists cache, indexes, and settings. Open http://localhost:8899.

--network host is recommended so LAN peer discovery (mDNS) and BitTorrent seeding work out of the box. If you can't use host networking, see "Bridge mode" below.

Docker Compose (recommended — host networking)

services:
  zimi:
    image: epheterson/zimi
    container_name: zimi
    restart: unless-stopped
    network_mode: host           # mDNS + BT seeding work without port plumbing
    volumes:
      - ./zims:/zims             # ZIM files go here
      - ./zimi-config:/config    # cache, indexes, settings

Docker Compose (bridge mode — no LAN discovery)

services:
  zimi:
    image: epheterson/zimi
    container_name: zimi
    restart: unless-stopped
    ports:
      - "8899:8899"
      - "6881:6881/tcp"          # BitTorrent (TCP)
      - "6881:6881/udp"          # BitTorrent (UDP / DHT)
    volumes:
      - ./zims:/zims
      - ./zimi-config:/config

LAN peer discovery (_zimi._tcp) won't reach the LAN in bridge mode — multicast doesn't cross the docker bridge, and Zimi warns in the Nearby settings when it detects this. Use host networking, or set ip=<your host's LAN address> in ZIMI_NEARBY. BT seeding still works because libtorrent binds the mapped port. See docs/deployment-networking.md for the full discussion.

Python

pip install zimi
ZIM_DIR=./zims zimi serve --port 8899

Environment Variables

Most people set nothing: every setting below has a sensible default or lives in the UI.

Variable	Default	Description
ZIM_DIR	/zims	Path to ZIM files (scanned for *.zim on startup)
ZIMI_DATA_DIR	/config (Docker) or $ZIM_DIR/.zimi	Cache, indexes, and settings. Mount separately in Docker.
ZIMI_MANAGE_PASSWORD	(none)	Protect library management
ZIMI_BT	on	BitTorrent: off, or on,port=6881,ratio=2,up=2048,seed=on,mirror=off,upnp=on,dht=on. seed, upnp, and dht default on. Fields you set are locked in the UI; fields you leave out stay UI-controlled. ratio=0 means never seed.
ZIMI_NEARBY	off	LAN sharing: off, or on,name=my-zimi,public=off,ip=192.168.1.20. Controls serving and fetching between your Zimi devices. Set ip= to your host's LAN address when running Docker in bridge mode.

Advanced

Variable	Default	Description
ZIMI_MANAGE	1	Library manager. 0 to disable entirely.
ZIMI_AUTO_UPDATE	0	Auto-update ZIMs (1 to enable; also a UI setting)
ZIMI_UPDATE_FREQ	weekly	daily, weekly, or monthly
ZIMI_RATE_LIMIT	60	Requests/min/IP for anonymous clients. 0 to disable.
ZIMI_RATE_LIMIT_TRUSTED	600	Budget for logged-in clients (and private-network clients on passwordless instances).
ZIMI_API_TOKEN	(none)	Pin the API token instead of generating in the UI
ZIMI_HOT_ZIMS	(none)	Comma-separated ZIM names to pre-warm at startup

API

Endpoint	Description
GET /search?q=...&limit=5&zim=...&fast=1&lang=...	Full-text search. fast=1 for title matches only. lang filters by language.
GET /read?zim=...&path=...&max_length=8000	Read article as plain text
GET /chunks?zim=...&path=...&size=1200&overlap=120	Deterministic, embedding-free article chunking for RAG clients
GET /suggest?q=...&limit=10&zim=...	Title autocomplete
GET /list	List all sources with metadata
GET /article-languages?zim=...&path=...	All languages an article is available in
GET /catalog?zim=...	PDF catalog for zimgit ZIMs
GET /snippet?zim=...&path=...	Short text snippet
GET /random?zim=...	Random article
GET /collections	List collections
POST /collections	Create/update a collection
DELETE /collections?name=...	Delete a collection
GET /resolve?url=...	Resolve external URL to ZIM path
POST /resolve	Batch resolve: {"urls": [...]}
GET /health	Health check with version
GET /w/<zim>/<path>	Serve raw ZIM content
GET /openapi.json	OpenAPI 3.1 description of the stable read API

Examples

# Search across all sources
curl "http://localhost:8899/search?q=python+asyncio&limit=5"

# Search in French only
curl "http://localhost:8899/search?q=eau&lang=fr&limit=5"

# Find all languages for an article
curl "http://localhost:8899/article-languages?zim=wikipedia&path=A/Water"

# Read an article
curl "http://localhost:8899/read?zim=wikipedia&path=A/Water_purification"

MCP Server

Zimi includes an MCP server for AI agents.

{
  "mcpServers": {
    "zimi": {
      "command": "python3",
      "args": ["-m", "zimi.mcp_server"],
      "env": { "ZIM_DIR": "/path/to/zims" }
    }
  }
}

For Docker on a remote host:

{
  "mcpServers": {
    "zimi": {
      "command": "ssh",
      "args": ["your-server", "docker", "exec", "-i", "zimi", "python3", "-m", "zimi.mcp_server"]
    }
  }
}

Tools: search (with lang filter), read, get_chunks, suggest, list_sources, random, article_languages, read_with_links, deep_search, list_collections, manage_collection, manage_favorites

Integrations

• SearXNG — route queries through Zimi from a self-hosted SearXNG metasearch instance.
• OpenWebUI / generic AI — wire the MCP server into any AI client for offline research.

Long-requested, shipped here

Every issue filed against Zimi has been answered — #33 country holiday colors, #34 new-ZIM badges and recency filters, #36 Tailscale-friendly management, #37 library organization, #38 fragment links and stray-torrent confusion. And features the wider ZIM ecosystem has been asking for, available today:

• Spelling suggestions — "did you mean?" on weak searches, fully offline (libzim #731)
• Read-aloud — text-to-speech in the reader via the offline Web Speech API (kiwix-js #166)
• Reader View — a clean, adjustable reading mode (themes, fonts, text size) for any article
• Word lookup — tap a word in any article, get the dictionary entry from your own library
• Resumable downloads — an interrupted ZIM download picks up where it left off, and updates reuse the unchanged pieces of the old file instead of re-downloading everything
• User accounts — named logins with per-ZIM access lists, so one server can serve the whole house (or classroom)
• A native Windows app — with the same auto-update channel as macOS
• Give back — seed your downloads to the Kiwix swarm at a ratio you choose, or flip one switch and be a full mirror
• Grab the file — a download button for any ZIM you're sharing on your network
• Real article counts — articles, not raw entry counts, on library cards

Contributing

See CONTRIBUTING.md.

License

MIT. Desktop and Docker builds bundle libtorrent-rasterbar (BSD-3-Clause) for BitTorrent transfers — see THIRD_PARTY_NOTICES.md.

---

Built with ❤️ in California by @epheterson and Claude Code.