Kiwix JS

Kiwix is your gateway for offline access to vast web resources like Wikipedia, Stackexchange, Project Gutenberg, TED Talks, and much more. These resources are packaged as highly compressed ZIM archives available for free from Kiwix. Learn more about the open-source Kiwix project on our main website.

Kiwix JS is our official HTML5/JavaScript version, primarily designed for browser extensions. Grab our free extension from the Mozilla, Chrome, and Edge extension stores. Check out the Store links for more details. We also offer an offline-first Progressive Web App (PWA) version at https://browser-extension.kiwix.org/current/. For a fully featured PWA based on Kiwix JS, visit https://pwa.kiwix.org.

To get started with Kiwix JS, download a free content archive (Usage), select it on your device, and start exploring articles. You can access the entire content of Wikipedia in your language, including images and audiovisual content, offline. Ideal for users with expensive, intermittent, slow, unreliable, or censored internet access. You can even load ZIM archives shared on a USB stick or external hard drive. No internet? No problem!

Kiwix supports all content in the OpenZIM format, including full support for Zimit content (based on the Web Archive format), both Zimit Classic and Zimit v2.0. Note: Some content requires your browser to support Service Workers.

Usage

Install "Kiwix JS" from your browser's add-on store. This is the best way to get the extension, because it will be kept up to date automatically. If you would rather not use a store, you can get a file-based version of the extension from http://download.kiwix.org/release/browsers/ (and follow instructions below), but you will have to update this manually.

Alternatively, you can bookmark or install the PWA version from https://browser-extension.kiwix.org/current/ (it will auto-update), or try our dedicated PWA version at https://pwa.kiwix.org. To install the PWA (in Chromium browsers), go to Settings -> Apps -> Install this site as an app.

As mentioned above, the app requires at least one ZIM archive of offline content. You can download one from the in-app library, or else in any browser go to https://library.kiwix.org (this has a nice, graphical interface and a preview of each ZIM archive) or from https://download.kiwix.org/zim/ (a more basic list of archives). You have to download these separately, store them in your filesystem, and manually select them after starting the application (or you can drag-and-drop one into the app).

Zimit-based archives (available from the "zimit" directory on https://download.kiwix.org/zim/, or made yourself with youzim.it), are fully compatible with this reader. For the best experience, you will need a modern browser and to allow the app to run in ServiceWorker mode as an offline-first PWA (see below for an explanation of what this means). If the app is running in any other mode, then only static content will be viewable (if at all). Our sister app https://pwa.kiwix.org has some further support for Zimit archives in older browsers.

Security

Be sure to get your ZIM archives only from a secure source, such as the official Kiwix library. This is because ZIM archives can run dynamic code in your browser. While we do our best to sandbox the ZIM's content, a determined malicious ZIM could remove the sandbox and redirect the iframe to, say, a phishing Web site. For this reason we now show a Security Warning when you open a ZIM with dynamic content in ServiceWorker mode for the first time. If you do not trust the source of the ZIM, and wish to browser static content safely, then open the ZIM first in Restricted Mode before deciding whether to switch to ServiceWorker Mode.

Compatibility

Since the app is written in HTML/JavaScript, it should work in most recent browser engines and many older ones too, depending on the Content Injection mode supported by the specific browser engine. Archives containing dynamic content (most non-Wikimedia archives) work better in ServiceWorker mode (see below), but unfortunately this is not available in many older browsers. If you wish to read such archives, we would suggest that you upgrade to a browser that supports Service Workers (Chrome 58+, Firefox 61+ [not ESR versions], Edge 17+, Safari 11.3+).

Officially supported platforms

• Mozilla Firefox >=56 (as an extension): Mozilla Add-ons Store
  • Firefox 52-56 and ESR version 58: Limited support (Restricted mode only)
• Chromium / Chrome / Edge >= 88 (as a Manifest V3 extension):
  • Google Chrome >=88: Chrome Web Store
  • Microsoft Edge >=88: Edge Add-ons Store
• Chromium / Chrome / Edge 58-87 (as a Manifest V2 extension): use the MV2 zip from the chrome or edge directory in https://download.kiwix.org/release/browsers/, and follow instructions below
• Safari >=11.3 on macOS or iOS: no extension available, but use https://browser-extension.kiwix.org and install to Home screen; for a more fully featured PWA, use https://pwa.kiwix.org
• Electron >=1.8.0 and NWJS >=0.14.7 (as an application for Linux and Windows): https://kiwix.github.io/kiwix-js-pwa/app
• Universal Windows Platform (UWP) >=10.0.10240 (as an HTML/JS application): Microsoft Store
• Ubuntu Touch (as an application): Ubuntu OpenStore

Deprecated platforms

These platforms/browsers are deprecated. We still partially test against them, and we'll try to keep compatibility as long as it's not too complicated:

• Firefox OS >=1.2: needs to be installed manually on the device with WebIDE
• Microsoft Edge Legacy >=17: no extension available, but bookmark https://browser-extension.kiwix.org or https://pwa.kiwix.org
• Microsoft Edge Legacy 15-16: needs to run a bundled version of the source code in Restricted mode only
• Microsoft Internet Explorer 11: needs to run a bundled version of the source code in Restricted mode only

You can build a bundled version by running npm install and npm run build in the root directory of this repo. Alternatively, a bundled version is served as a web app for testing from https://kiwix.github.io/kiwix-js/dist/ (also available on the gh-pages branch of this repo, under /dist).

Installing signed or unsigned extension files in Chromium

If you need to install Chromium (Chrome or Edge) extension from a file instead of from a Store, e.g. if your browser doesn't support Manifest V3, then you will need to download a signed or unsigned CRX or ZIP file from a relevant directory in https://download.kiwix.org/release/browsers/, or else a nightly version from https://download.kiwix.org/nightly/. Files with mv2 in their filename are in the legacy Manifest V2 format.

To install your CRX or ZIP, open the extension management page in your browser, e.g. chrome://extensions/ or edge://extensions/, and turn on Developer mode. Now, you should be able to drag and drop the ZIP file into this page. Verify the extension is showing in the management page.

Files that we deliver with a .crx file extension are files that have been validated by the Edge or Chrome Stores, and you should be able to install these as "first-class" apps. ZIP files provided in https://download.kiwix.org/release/browsers/, or the ones labelled signed in nightly, are actually signed CRX files that have been renamed with a .zip extension to facilitate downloading and installing them in Chromium browsers. Although signed, you cannot install them as CRX files, because they have not been validated by the Chrome or Edge Stores. For this reason, the browser will periodically ask you if you want to turn off developer-mode extensions. Just choose "ask again in two weeks".

If drag-and-drop is difficult, you can instead unzip the extension ZIP into a folder, and note the location. Then select "Load unpacked" and choose the folder that contains the unzipped extension. To unzip the MV2 files with a utility like 7Zip, you will need to change the extension name to .crx. On Linux, unzip can read them without changing the filename.

Self-hosting with Docker

Kiwix JS is also published as a container image to the GitHub Container Registry (GHCR) on every release, allowing you to self-host your own instance of the browser-based application available at browser-extension.kiwix.org.

Clone this repository and use the provided docker-compose.yml to get started immediately:

docker compose up -d

Or pull and run the published container image directly (replace 8080 with your preferred port):

docker run -d -p 8080:80 ghcr.io/kiwix/kiwix-moz-extension:latest

Then open http://localhost:8080 in your browser. With docker compose, you can omit -d to run in the foreground and view logs. You can also change the host port in docker-compose.yml.

Important notes:

• ZIM archives must still be selected manually through the application's file picker. Because Kiwix JS is a web application, it uses browser APIs to access local files, so archives must be available on the machine where the browser is running or via a network mount. If you need to serve ZIM archives over a local network, consider using kiwix-serve.
• When accessed via localhost, Kiwix JS runs in full ServiceWorker mode. If served over a LAN withou