kiwix-serve is a tool for serving ZIM file content over HTTP. It supports
serving a library containing multiple ZIM files. In a large library served by a
kiwix-serve instance clients can look up/filter ZIM files of interest by
words in their titles and/or descriptions, language, tags, etc.
kiwix-serve provides a ZIM file viewer for displaying inidividual pages
from a ZIM file inside the user’s web browser (without downloading the full ZIM
Clients can also remotely search inside those ZIM files that contain a full-text search database.
kiwix-serve --library [OPTIONS] LIBRARY_FILE_PATH kiwix-serve [OPTIONS] ZIM_FILE_PATH ...
LIBRARY_FILE_PATH: path of an XML library file listing ZIM files to serve.
To be used only with the
--library option. Multiple library files can
be provided as a semicolon (
;) separated list.
ZIM_FILE_PATH: ZIM file path (multiple arguments are allowed).
- -i ADDR, --address=ADDR¶
Listen only on this IP address. By default the server listens on all available IP addresses.
- -p PORT, --port=PORT¶
TCP port on which to listen for HTTP requests (default: 80).
- -r ROOT, --urlRootLocation=ROOT¶
URL prefix on which the content should be made available (default: empty).
- -d, --daemon¶
Detach the HTTP server daemon from the main process.
- -a PID, --attachToProcess=PID¶
Exit when the process with id PID stops running.
- -M, --monitorLibrary¶
Monitor the XML library file and reload it automatically when it changes.
- -m, --nolibrarybutton¶
Disable the library home button in the ZIM viewer toolbar.
- -n, --nosearchbar¶
Disable the searchbox in the ZIM viewer toolbar.
- -b, --blockexternal¶
Prevent the users from directly navigating to external resources via such links in ZIM content.
- -t N, --threads=N¶
Number of threads to run in parallel (default: 4).
- -s N, --searchLimit=N¶
Maximum number of ZIM files in a fulltext multizim search (default: No limit).
- -z, --nodatealiases¶
Create URL aliases for each content by removing the date embedded in the file name. The expected format of the date in the filename is
_YYYY-MM. For example, ZIM file
wikipedia_en_all_2020-08.zimwill be accessible both as
- -c PATH, --customIndex=PATH¶
Override the welcome page with a custom HTML file.
- -L N, --ipConnectionLimit=N¶
Max number of (concurrent) connections per IP (default: infinite, recommended: >= 6).
- -v, --verbose¶
Print debug log to STDOUT.
- -V, --version¶
Print the software version.
- -h, --help¶
Print the help text.
HTTP API endpoints presented below are relative to that location, i.e.
/foo/bar must be actually accessed as
Welcome page is served under
/. By default this is the library page, where
books are listed and can be looked up/filtered interactively. However, the
welcome page can be overriden through the
command line option of
/catalog/v2 (OPDS API)¶
The new OPDS API of
kiwix-serve is based on the OPDS Catalog specification
v1.2. All of its endpoints are grouped under
Legacy OPDS API is preserved for backward compatibility.
The OPDS Catalog Root links to the OPDS acquisition and navigation feeds accessible through the other endpoints of the OPDS API.
Returns the full list of ZIM file categories as an OPDS Navigation Feed.
By default, all entries in the library are returned. A subset can be requested by providing one or more filtering criteria, whereupon only entries matching all of the criteria are included in the response. The filtering criteria must be specified as URL search parameters.
lang- filter by language (specified as a 3-letter language code).
category- filter by categories associated with the library entries.
tag- filter by tags associated with the library entries. Multiple tags can be provided as a semicolon separated list (e.g
tag=wikipedia;_videos:no). The result will contain only those entries that contain all of the requested tags.
notag- filter out (exclude) entries with any of the specified tags (example -
maxsize- include in the results only entries whose size (in bytes) doesn’t exceed the provided value.
q- include in the results only entries that contain the specified text in the title or description.
name- include in the results only the entry with the specified name.
count=n- these parameters enable pagination of the search/filtering results - the feed will contain (at most)
nresults starting from the result #
# List only books in Italian (lang=ita) but # return only results ## 100-149 (start=100&count=50) $ curl 'http://localhost:8080/catalog/v2/entries?lang=ita&start=100&count=50' # List only books with category of 'wikipedia' AND containing the word # 'science' in the title or description $ curl 'http://localhost:8080/catalog/v2/entries?q=science&category=wikipedia'
Returns full info about the library entry with UUID
Returns the illustration of size
NxN pixels for the library entry with
If no illustration of requested size is found a HTTP 404 error is returned.
Returns the full list of ZIM file languages as an OPDS Navigation Feed.
Supported filters are the same as for the /catalog/v2/entries endpoint.
/catalog (Legacy OPDS API)¶
The legacy OPDS API is preserved for backward compatibility and is deprecated. New OPDS API should be used instead.
Full library OPDS catalog (list of all ZIM files).
Returns the list of ZIM files (in OPDS catalog format) matching the search/filtering criteria. Supported filters are the same as for the /catalog/v2/entries endpoint.
Generates a HTML page with a link leading to (the decoded version of)
and a warning that following that link will load an external (out of ZIM)
source: URL of the external resource (must be URL-encoded).
# Intercept an external link to https://example.com?query=abcd $ curl 'http://localhost:8080/catch/external?source=https%3A%2F%2Fexample.com%3Fquery%3Dabcd'
ZIM file content is served under the
/content endpoint as described below.
Returns the entry with path
PATH/IN/ZIMFILE from ZIM file with name
/content/ZIMNAME redirects to the main page of the ZIM file with name
ZIMNAME (unless that ZIM file contains an entry with an empty
path or path equal to
/, in which case that entry is returned).
Generates a HTTP redirect to a randomly selected article/page from the specified ZIM file.
content: name of the ZIM file.
Returns the entry with path
PATH/IN/ZIMFILE from the ZIM file with
ZIMNAME. Currently, this endpoint almost duplicates
(with some subtle technical differences) the newer endpoint
/content/ZIMNAME/PATH/IN/ZIMFILE. The important difference is that the
/raw endpoint guarantees that no server-side processing will be applied to
the returned content, whereas content obtained via the
may in the future undergo some processing intended to improve the operation of
the viewer (e.g. compensating for certain bugs in ZIM creation).
Returns the metadata item
METADATAID from the ZIM file with name
Performs a full text search on one or more ZIM files and returns an HTML page with a list of links to matching pages along with snippets of the matching portions of those pages.
A multi-ZIM search request must comply with the following constraints:
the number of ZIM files participating in the search operation must not exceed the limit imposed by the
all of the ZIM files participating in the same search operation must be in the same language.
ZIM file selection parameters:
At least one of the following parameters must be provided in order to specify in which ZIM file(s) to search. Parameters appearing earlier in below list take precedence over subsequent ones (the later ones, even if present in the request, are simply ignored).
content: name of the ZIM file (for a single-ZIM search). This is a legacy parameter.
books.nameshould be used instead.
pattern(optional; defaults to an empty string): text to search for.
distance(optional): geospatial query parameters. If all of these are provided, then the results will be restricted to geotagged pages that are within
distancemetres from the location on Earth with coordinates
pageLength(optional, default: 25): maximum number of search results in the response. Capped at 140.
start(optional, default: 1): this parameter enables pagination of results. The response will include up to
pageLengthresults starting with entry #
startfrom the full list of search results (the first result is assumed to have index 1).
Cache busting of
static resources is supported via the optional param
cacheid. By default,
i.e. when the
cacheid parameter is not specified while accessing the
/skin endpoint, static resources are served as if they were dynamic (i.e.
could be different for an immediately repeated request). Specifying the
cacheid parameter with a correct value (matching the value embedded in the
kiwix-serve instance), makes the returned resource to be presented as
immutable. However, if the value of the
cacheid parameter mismatches then
kiwix-serve responds with a 404 HTTP error.
Returns suggestions (in JSON format) for a text string that is assumed to be a partially typed search for a page inside a particular ZIM file.
Suggestions are obtained as matches of the query text against the page titles in the ZIM file using the title index database generated during the creation of the ZIM file.
In case of a multi-word query the order of the words matters in two ways:
the last word is considered as partially typed, unless followed by a space;
ranking of the matches.
If the ZIM file doesn’t contain a title index then suggestions are generated by listing page titles starting exactly (in a case sensitive manner) with the query text. Otherwise, suggestions are case-insensitive.
If the ZIM file contains a full text search index, then an extra suggestion is added as an option to perform a full text search in the said ZIM file.
content(mandatory): name of the ZIM file.
term(optional; defaults to an empty string): query text.
count(optional, default: 10): maximum number of page suggestions in the response (i.e. the extra option to perform a full text search is not included in this count).
start(optional, default: 0): this parameter enables pagination of results. The response will include up to
countentries starting with entry #
startfrom the full list of page suggestions (the first result is assumed to have index 0).
$ curl 'http://localhost/suggest?content=stackoverflow_en&term=pyth&count=50'
ZIM file viewer. The ZIM file and entry therein must be specified via the hash
component of the URL as
Settings of the ZIM file viewer that are configurable via certain command line
Any other URL is considered as an attempt to access ZIM file content using the
legacy URL scheme and is redirected to
- ZIM filename¶
Name of a ZIM file on the server filesystem.
- ZIM name¶
Identifier of a ZIM file in the server’s library (used for referring to a particular ZIM file in requests).
kiwix-servestarted with a list of ZIM files, ZIM names are derived from the filename by dropping the extension and replacing certain characters (spaces are replaced with underscores, and
+symbols are replaced with the text
plus). Presence of the
--nodatealiasesoption will create additional names (aliases) for filenames with dates.
kiwix-servestarted with the
--libraryoption, ZIM names come from the library XML file.
- ZIM title¶
Title of a ZIM file. This can be any text (with whitespace). It is never used as a way of referring to a ZIM file.
- ZIM UUID¶
This is a unique identifier of a ZIM file designated at its creation time and embedded in the ZIM file. Certain
kiwix-serveoperations may require that a ZIM file be referenced through its UUID rather than name.