Install on Linux
Docker is the supported way to run Maki on Linux. Use the tarball where Docker is not an option, such as a Proxmox LXC container or a small NAS. Every release is built and smoke-tested in CI on x64 and arm64. Nobody tests each distribution by hand, so the tarball is a community tier. If Docker is an option, use Docker Compose.
Requirements
Section titled “Requirements”- A 64-bit glibc distribution, on x64 or arm64. Alpine and other musl systems are not supported.
- About 350 MB to download the MangaBaka database and 3.5 GB on disk, on top of your library. The first search by meaning adds about 110 MB for a memory-mapped copy of the search model.
The tarball carries its own .NET runtime, so Maki itself needs nothing else installed. The libjxl files it ships, used to save upscaled colour pages as JPEG XL, need glibc 2.39 or newer (Ubuntu 24.04, Debian 13, Fedora 40 or later). On an older system colour pages are saved as WebP instead, which works the same in the reader. Browser-based sources need a few system libraries. See Sources that need a browser.
Install
Section titled “Install”- Download the tarball for your machine from GitHub releases:
Maki-<version>-linux-x64.tar.gzorMaki-<version>-linux-arm64.tar.gz. - Unpack it, then start Maki from the new folder:
tar -xzf Maki-<version>-linux-x64.tar.gzcd maki./Maki.Api- Open
http://<address>:8990and create the administrator account. The setup guide opens next.
Linux builds listen on every network interface by default, so other devices can reach Maki at once. To keep it to this machine, turn off Allow other devices on your network under Settings → System → Network, then restart Maki.
To check the bundled libraries (libjxl included) and web files without starting the server, run ./Maki.Api --selftest.
Run it as a service
Section titled “Run it as a service”The tarball includes maki.service, a sample systemd unit. It runs Maki as a maki user from /opt/maki, with its data in /var/lib/maki. Run these from the unpacked maki folder:
sudo useradd --system --home /var/lib/maki --create-home makisudo mkdir -p /opt/maki && sudo cp -r . /opt/maki && sudo chown -R maki:maki /opt/makisudo cp maki.service /etc/systemd/system/sudo systemctl daemon-reloadsudo systemctl enable --now makiThe maki user needs read and write access to your library folders.
The unit restarts Maki whenever it stops. Maki stops itself on purpose after a restore or a restart from Settings, and the unit starts it again. Without the service, a stopped Maki stays down until you start it by hand.
Sources that need a browser
Section titled “Sources that need a browser”MangaFire and TopManhua drive a headless browser. Maki downloads it the first time one of those sources needs it. The browser also needs some system libraries. If Health reports that it will not start, install them once:
sudo /opt/maki/.playwright/node/linux-x64/node /opt/maki/.playwright/package/cli.js install-deps chromium-headless-shellOn an arm64 machine, use linux-arm64 in the path. If you run Maki from the unpacked folder instead of /opt/maki, use that folder’s path. Both sources also need FlareSolverr.
Where your data lives
Section titled “Where your data lives”Without the service, Maki keeps its data in ~/.config/Maki. With the service, it is /var/lib/maki. Set MAKI_CONFIG_DIR to put it somewhere else. The database, config.json, covers, backups and logs all live there. The full list is in Ports, paths and files.
Keep the data folder out of the app folder. Updates replace /opt/maki, and they leave the data folder alone.
Updates
Section titled “Updates”The tarball does not update itself. When a new version is out, Maki shows Update available under Settings → System → Updates. To update, download the new tarball and replace the app folder. Your data stays where it is.
sudo systemctl stop makitar -xzf Maki-<version>-linux-x64.tar.gzsudo rm -rf /opt/makisudo cp -r maki /opt/makisudo chown -R maki:maki /opt/makisudo systemctl start makiWithout the service, stop Maki, replace the unpacked folder, and start it again. Before an update changes the database, Maki takes a backup. If an update goes wrong, install the previous tarball and restore that backup under Settings → System → Backup & restore. See Upgrading for more.