# Kiwix
Offline Wikipedia reader

Caching assets...

## Kiwix : offline Wikipedia viewer

Official site : https://www.kiwix.org

- About this App
- Usage
- Title Search Usage
- Privacy Policy
- Expert Settings and Technical Information
  - ZIM Archive Format
  - Downloading and Storing Large Archives
  - JQuery and ServiceWorker Modes
- Feedback/Helping/Contributing
- Credits
- Licence Information
- Other Platforms/Versions
- Download ZIM archives (content):
  - Download by language
  - Index of all files

#### About this app

If your Internet access is expensive, slow, unreliable, insecure or censored, you can still gain free offline access to vast repositories of human knowledge and culture. Carry the world's largest Encyclopaedia around in your pocket, in any language, or a worldwide Travel Guide when you are on the road!

To use this app, you will need to download one or more archives (called ZIM archives) from the Kiwix website and store them on your device or a thumb drive. You will then be able to access Wikipedia, Wiktionary, WikiMed, Wikivoyage and many other sources offline, even if you are undertaking a long plane journey, hiking, and travelling or living in areas with weak Internet access.

You can search through article titles and read any of these articles (including the images) completely offline. Archives are available with content in many different languages. There are "themed" archives with selected topics of interest from Wikipedia such as medicine, movies, history, geography, maths, physics, chemistry or computing (amongst many others).

↑ Back to Contents

### Usage

#### Step 1: Download some content

Go to https://download.kiwix.org/zim , with a regular computer and download an archive that interests you. If you find the list overwhelming, you can limit the selection by language on the Download-by-language site . Note that archives with "mini" in their name only contain the lede (first) portion of each article; "nopic" means no pictures; "maxi" means everything except video and audio. Larger versions without any of these qualifiers contain everything, though pictures are always compressed.

Currently only Mediawiki-based content (for instance Wikipedia and Wikivoyage ), and StackExchange , have been thoroughly tested. Dynamic content (e.g. PhET) is only supported in ServiceWorker Mode (see technical explanation below).

For a quick test, you can start with the Ray Charles ZIM file , which contains some Wikipedia articles about the Jazz musician, or a small archive containing the top 100 English Wikipedia articles and images .

After that, download any content in your favourite language(s). Check the size before you download archives as many file sizes are very large (several Gigabytes). Themed versions such as WikiMed, or versions without images are smaller than full Wikipedia archives and can be readily downloaded in your browser. Kiwix ZIM archives are completely open source and free to download.

See Downloading large archives below for details of how to download very large files.

#### Step 2: Copy the content onto your device

If you have enough space, you can put several archives on your device! If you don't have enough internal storage, consider using a modern microSD card or thumb drive. For larger archives (greater than 2GB) on older devices, it is possible that an archive might not be supported if your storage is formatted using a FAT filesystem (NB exFAT is fine). See technical information below for a solution.

#### Step 3: Drag and drop the file into the app

You can drag and drop the archive file into the the open app (if you have a split file, be sure to drag all parts), or else you can go to the "Configure" menu and select your ZIM file.

#### Step 4: Enjoy your offline content!

↑ Back to Contents

### Title search usage

Title search matches the start of an article title, so if you search for 'France' you will get 'France (country)', 'France (disambiguation)', 'France (film)', etc. This kind of search tries to be case-insensitive, but the number of case variants tried is necessarily limited: e.g. if you search for 'unesco world heritiage', it will try 'Unesco world heritage', 'UNESCO world heritage', 'unesco World heritage', 'Unesco WORLD heritage' (etc.), but it won't try 'uNesCO' and other non-obvious case combinations. If you want to search for 'uNesCO', then you must type it exactly like that.

If not enough results are returned, you can increase the maximum number of search results using the slider in Configuration. Please note that we are currently unable to support full text search of the contents of articles and titles, though we have plans to do so in the future if it becomes technically possible.

Alphabetical search: If you type a letter of the alphabet in the title search box (upper case may be most useful), it will show an alphabetical list of articles starting with that letter (up to the maximum number of search results you selected in Configuration). This is useful for ZIM archives that have descriptive rather than semantic titles (e.g. TED Talks), expecially in JQuery mode.

↑ Back to Contents

### Privacy policy

#### Short version:

Kiwix JS works offline, and does not collect or record any of your personal data. It only remembers your browsing history for the duration of a session (for the purpose of returning to previously viewed pages). This history is lost on exiting the app and is not recorded in any way.

#### Longer version:

This application only reads the archive files that you explicitly select on your device together with files in its own package. Some ZIM archives contain active content (scripts) which may, in rare circumstances, attempt to contact external servers for incidental files such as fonts. These scripts will only run if you enable ServiceWorker Mode in Configuration. Nevertheless, if you believe your Internet access is insecure, or is being observed or censored, we recommend that you completely shut down your Internet (Data or WiFi) access before using the application.

Additionally, if you obtained this app from a vendor Store (including extensions), then the Store operator may track your usage of the app (e.g. download, install, uninstall, date and number of sessions) for the purpose of providing anonymous, aggregate usage statistics to developers. If this concerns you, you should check the relevant Store Privacy Policy for further information.

↑ Back to Contents

### Expert settings and technical information

#### ZIM archive format

Offline archives use the OpenZIM format , but note that this app has only been tested extensively on Wikipedia, WikiMedia and Stackexchage archives. Video content is in principle supported if your device, browser or OS understands the format. Some other ZIMs use a proprietary dynamic UI which is only supported in ServiceWorker Mode (see below).

#### Downloading and storing large archives

Full version of Wikipedia can be enormous: French, German and Spanish Wikipedia with images are each >25GB; full English Wikipedia with images is >90GB. For these very large archives you can find convenient Torrent links which may be more reliable than attempting to use your browser. You can use an open-source BitTorrent client such as QBittorrent with these links (install the software before clicking on the torrent link).

If you need to store a large ZIM archive on an older filesystem formatted as FAT16 or FAT32, you need to be aware of the file size limits of those systems (FAT16 < 2GiB; FAT32 < 4GiB). Most modern microSD cards, thumb drives or hard drives are formatted as exFAT or another modern FS such as NTFS, which do not have this issue. If your ZIM archive is larger than the FS limit, it is possible to split the archive into several 2GiB-1 or 4GiB-1 files (or smaller). You will need to give a file extension to each chunk in the right order following this pattern: `*.zimaa`, `*.zimab`, `*.zimac`, `...`, etc.). When you pick this archive in the app, be sure to pick all the chunks, or drag-and-drop them all into the app.

For some information on how to split archves, see Archive of the Kiwix FAQ (current FAQ is here ).

↑ Back to Contents

#### JQuery and ServiceWorker Modes

Depending on your browser or framework, this app may be capable of running in two different modes, which we call "JQuery Mode" and "ServiceWorker Mode" for short. There is a toggle under Expert Settings in Configuration. Here is a technical explanation of what these modes do:

- JQuery Mode: This mode (which does not in fact require JQuery) is fine for everyday use with Wikipedia / WikiMedia archives, and is stable and safe. It is a way of inserting articles extracted from the ZIM into the DOM (browser document) by injecting the content into an iframe or tab. We then use native DOM methods, or sometimes JQuery, to parse the article's HTML and insert required assets (images, stylesheets, event listeners for hyperlinks, etc.). On old devices DOM traversal can be slow, but it is compensated for because we do not extract or run JavaScript assets (which would be technically extremely complicated). As a result, for WikiMedia archives this mode is usually quite fast. On the downside, ZIMs that have a proprietary dynamic UI (such as Gutenberg or TED talks) are only partially supported in this mode: the UI does not work, but articles can be searched for and loaded from the search bar.
- ServiceWorker Mode: This mode, as its name implies, requires that the browser or framework be capable of installing a Service Worker. It works by intercepting the browser or framework's Fetch calls (network requests) and supplying the requested content from the ZIM. This mode requires no DOM traversal, and the content is read and supplied as-is from the archive. Dynamic content (e.g. JavaScript) and proprietary UIs are fully supported in this mode. It can feel initially a little slower while commonly used assets are being cached, but it soon equals JQuery mode in speed, at least in modern browsers. However, older browsers such as IE11 do not support this mode, and the app must be running in a secure context (`https:`, `localhost`, or certain browser extensions). Unfortunately, this mode is not currently supported in Mozilla (Firefox) browser extensions. It is supported in Chromium browser extensions (e.g. Chrome or new Edge). Note that this mode cannot run with the `file:` protocol (but only IE11 and old Edge allow the app to run by launching `index.html` from the file system).

↑ Back to Contents

### Feedback / helping / contributing

We welcome constructive feedback and suggestions for improvement. We will consider feature requests, but it is even better if you can contribute to improving the app! The source code is on GitHub , and we welcome Pull Requests (it's worth opening an issue and discussing your proposal first).

The bug and issue tracker is on GitHub too. We use it as our roadmap.
Alternatively, you can send your feedback by email.
In all cases, if you are reporting a bug, please give as much detail as you can: which device you are using, which version of Kiwix, which archive, which articles etc.

If you like the Kiwix project and use it, please consider giving donations:

- to the Wikimedia foundation, to help maintaining their servers and article contents. See the donation page
- to Kiwix, to help maintaining the ZIM files and applications. There is a donation button in the home page of kiwix.org

You can also help by:

- Adding articles or improving the existing ones, by editing online wikipedia articles
- Participating in the Kiwix project

↑ Back to Contents

### Credits

We owe a big debt of gratitude to:

- Kelson and all the Kiwix community for welcoming us in this project
- Wikipedia teams and contributors to help spreading knowledge to everybody
- All the developers of libraries and tools we used, for releasing them as Free software (see Licence paragraph)

↑ Back to Contents

### Licence information

Copyright 2013-2021 Mossroy, Peter-x, Jaifroid, sharun-s and other contributors
This application is licensed under the GPL v3 Licence:
Kiwix is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public Licence as published by
the Free Software Foundation, either version 3 of the Licence, or
(at your option) any later version.
Kiwix is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public Licence for more details.
You should have received a copy of the GNU General Public Licence
along with Kiwix (file LICENSE-GPLv3.txt). If not, see https://www.gnu.org/licenses/
Main libraries and resources used:

- jQuery 3, released under the MIT Licence
- Bootstrap 4, released under an MIT Licence
- Fontawesome Free, icons licensed under CC BY 4.0 Licence, code licensed under a MIT Licence
- RequireJS 2, released under the MIT Licence or new BSD Licence
- QUnit 2, released under the MIT Licence
- Kiwix logo from kiwix.org, released under the Creative Commons Attribution Share Alike Licence
- OpenZIM specifications from www.openzim.org, released under the Creative Commons Attribution Share Alike Licence
- Emscripten to generate XZ and ZSTD decompressors in javascript : https://github.com/kripken/emscripten, released under the MIT Licence
- XZ Embedded (the XZ library converted to Javascript with Emscripten), in public domain
- The Zstandard library, released under a BSD Licence and a GPLv2 Copying Licence
- The WebP-Hero browser polyfill, copyright Chase Moskal, released under an ISC Licence

↑ Back to Contents

### Other platforms/versions

Other Kiwix clients exist on various platforms such as desktop and mobile apps for Linux, Windows, Android and iOS.

See the official download site: https://www.kiwix.org/download

↑ Back to Contents

## Configuration

This application needs a ZIM archive to work. For download instructions, please see the About section

Drag and drop a new ZIM file, or display file selectors

Please select or drag and drop the .zim file (or all the .zimaa, .zimab etc in case of a split ZIM file)

Only Mediawiki-based (wiki*.zim* files, like wikipedia), StackExchange and some video-based ZIMs (e.g. TEDx) have been tested. Dynamic content is not currently supported in jQuery mode.
Scanning for archives... Please wait
Please select the archive you want to use :
Rescans your SD Cards and internal memory

### Display settings

Display options:
Permanently hide active content warning (for experienced users)
Animate transition between app pages
Use Home key to focus search bar (may rarely have side effects on ZIM files that handle Home key)
Select app theme (content inversion is experimental):

* Implements workarounds specific to Wikimedia ZIMs. Try generic option if there are display errors with recent ZIMs.

[ Show article with applied theme ]

### Performance settings

Speed up archive access

Kiwix JS can speed up the display of articles by caching assets:

Cache assets (recommended)
Do not cache assets (empties caches: for low-memory devices)

Select max number of search results:

Value: (default 25, higher values increase search time)

### Expert settings

Content injection mode

See About (Expert Settings) for an explanation of the difference between these modes:

JQuery (stable and safe)
ServiceWorker (not available on all platforms, but supports more ZIM files)
API Status
You can search the content of your ZIM archive by typing in the above search field.
It will suggest articles starting with the letters you type.
Unable to display active content: This ZIM is not fully supported in jQuery mode.
Content may be available by searching above (type a space or a letter of the alphabet), or else switch to Service Worker mode if your platform supports it. [Permanently hide]