How to Use Komga: The Beginner's Guide (First Install, the Admin-First Rule, First Library, and the Scan Lesson)

CodexFuse Team · 2026-11-01T01:14:12.281Z · 15 min read

Learn how to use Komga: install the self-hosted comics server with Docker, claim the admin account, build your first library, master scanning and OPDS reading.

If your comic collection lives in a dozen folders with names like "to sort" and "final final," learning how to use Komga is the project that turns the mess into a library. Komga is the free, open-source comics, manga, and ebook server you run on your own hardware: point it at your folders, and it catalogs every series, serves a clean web reader, and syncs your reading progress to your phone, tablet, and e-reader. This Komga tutorial is written as the komga for beginners walkthrough: installing with Docker, the admin-first rule that surprises every newcomer, creating your first library, the folder-structure lesson that makes scanning work, the scan lesson itself, reading on every device through OPDS, and sharing with family using age ratings. New to the whole container game? Start with our Docker beginner guide — Komga rides on Docker the way most self-hosted apps do.

What Is Komga?

Komga is a self-hosted comics/manga/ebook server: you install it once, give it your book folders, and it becomes your personal comic library with a web reader, a REST API, and OPDS feeds that let third-party apps read from it. Unlike a folder of CBZ files, Komga tracks series, reading progress, collections, and metadata — and it does it entirely on hardware you own. If you have ever wondered what an open source manga server looks like in practice, this is the answer: free software, your files, your server, no subscriptions. You can poke around before installing — the official demo server at demo.komga.org logs you in with the address [email protected] and the password komga-demo, and the source lives on GitHub at gotson/komga, where version 1.29.2 shipped on October 28, 2026.

What Do You Need Before You Install Komga?

You need three things: a machine that stays on, Docker, and a folder of books you actually own. The machine can be a home NAS, an old PC, or a small cloud server — our what is VPS hosting guide explains the VPS option if you don't have hardware at home. Docker is the recommended install path on Linux, and the Docker beginner guide walks you through the Docker basics this tutorial assumes. One rule before anything else: only host comics you own or that are licensed for it — Komga is a reader and organizer for your library, not a store.

How Do You Install Komga with Docker?

The official komga docker route is a short compose file, and it is the path the komga.org docs recommend for beginners. Here is the canonical first-deploy compose file, based on the official Docker installation guide:

services:
  komga:
    image: gotson/komga
    container_name: komga
    volumes:
      - /home/komga/config:/config
      - /home/komga/data:/data
    ports:
      - 25600:25600
    user: "1000:1000"
    environment:
      - TZ=America/New_York
    restart: unless-stopped

Three things matter in that file. First, the image is gotson/komga (also mirrored on ghcr.io). Second, the two volumes split responsibilities: /config holds the SQLite database and all settings, /data holds your books — keep them separate so a container rebuild never touches your library. Third, the default port is 25600, so the web UI lives at http://your-server:25600 after the container starts. The user: "1000:1000" line makes Komga run as your normal user instead of root, which keeps file permissions sane. Run docker compose up -d, give it a minute, then open the port in your browser.

The First 30 Minutes: A Numbered Checklist

Do these in order — they stack on each other:

1. Start the container with the compose file above and open http://your-server:25600.
2. Create the very first account — this becomes your administrator (see the next section).
3. Open the admin settings and confirm the /config path is on a local disk.
4. Add your first library pointing at one test series folder.
5. Let the first scan finish, then check that the series page looks right.
6. Generate an OPDS feed and connect your phone or e-reader to it.
7. Create a second, restricted user and test the age-rating limits.

Why Does the First Account Become the Admin?

The first account you register on a fresh Komga install is automatically the administrator — there is no separate setup wizard, and the server will refuse to be claimed if a user already exists. This is the number-one beginner surprise, and it comes with a security lesson the official FAQ states plainly: the server "has already been claimed" if a database user exists, which means whoever creates the first account owns the server. So create that first account before you expose port 25600 to the internet or share the address with anyone. Open it locally, register with your email and password (the Olares setup guide documents this first-run registration flow, updated October 31, 2026), and only then think about remote access.

Why Must the /config Folder Live on a Local Filesystem?

Komga keeps its database inside /config, and SQLite databases do not tolerate network storage. The official Docker installation guide carries this warning verbatim: "Always use a local filesystem for the /config folder. Do not use any network share like CIFS or NFS." Your books in /data can live on a NAS share if you must, but the database cannot — a network-backed /config risks corruption and mysterious lock errors. On a NAS install, that means creating the config folder on the NAS's local volume, not on an external mount. Two more tuning facts from the official docs: the Java heap defaults to roughly 1 GB, which you raise with JAVA_TOOL_OPTIONS=-Xmx4g for very large libraries, and the application.yml configuration file does not exist by default — you create it in /config only when you need to customize something beyond the web settings.

How Do You Create Your First Komga Library?

A library is a group of books with a root folder — you point Komga at the folder, it scans everything under it, and that becomes one library. In the web UI, go to Administration, add a library, and choose its type: comics for comics, manga, and BD, or books for EPUBs and PDFs. The type changes how the reader presents pages versus reflowable text, so put manga in a comics library and novels in a books library. Root folders must not overlap — two libraries can never point at the same folder or at folders nested inside each other. Start with a single test folder of one series so you can see the scan lesson play out before you add your whole collection.

How Should You Organize Your Comic Folders?

The scan is only as good as the folder structure, and this is where most beginners lose hours. Komga's rule is simple: one series folder holds that series' files, and the folder name is the series title unless metadata says otherwise. A structure like /data/comics/Series Name/Series Name v01.cbz works; a single folder with 400 unsorted CBZ files does not. The metadata lesson from the official FAQ matters here: Komga automatically imports metadata from EPUB files and from ComicInfo.xml inside CBZ/CBR archives, and imported metadata overrides the file and folder names. So if your files carry embedded ComicInfo.xml (tools can write it from ComicVine or the Grand Comics Database, per the diversetechgeek review), you get correct series, numbers, and summaries for free — and if they don't, the folder and file names do the work, so make them accurate.

How Does the Komga Scanner Work?

Komga scans your libraries on server startup and then on a schedule you set — not instantly when you add a file, which is the scan lesson that confuses newcomers. The scan interval offers disabled, hourly, every 6 hours, every 12 hours, or daily and weekly options. The scanner reads CBZ, ZIP, CBR, RAR, PDF, and EPUB files (note the mariushosting caveat: CBR works except RAR5 and solid archives). Beyond reading files, the analysis options compute a file hash, a page hash for CBZ files, a KOReader sync hash, and page dimensions. Two beginner-friendly features deserve attention: Komga can automatically repair files with incorrect extensions, and it can automatically convert CBR/RAR archives to CBZ so every file in your library uses one stable format. There is also a library trash — deleted files go there until you empty it — so an accidental deletion is recoverable. Watch the scan indicator after adding a big folder: drop ten thousand books in and walk away; scanning is not a real-time watcher.

How Do You Read Komga on Your Phone, Tablet, and E-Reader?

Komga exposes your library through its komga opds integration — the open standard for book catalog feeds — and the official docs put it plainly: "Komga should work with any OPDS reader, whether they use OPDS v1 or v2." That makes Komga a genuinely self hosted comic reader across your devices: add the OPDS URL to your reader app of choice and your whole library appears. The best clients right now are Komelia (free, open-source, cross-platform, built specifically for Komga), the Mihon extension, Paperback and Panels on iOS (Panels' own OPDS page-streaming extension is now in Komga, contributed by the Panels team), and KOReader or a Kobo with native Kobo sync on e-readers. Two honest caveats: Komga has no first-party app — you read through the web UI or a third-party client — and the official reader list states outright that Chunky Reader does not work with Komga 1.4.0 and later, so don't buy a client before checking compatibility.

How Do You Share Komga with Family?

Komga's user accounts are built for households. The admin creates users and assigns roles — Administrator, Page Streaming, and File Download control who can manage, read, and download — and each user can be restricted to specific libraries and to content by age rating and custom labels, where an exclusion always wins. That means the kids' tablets get the all-ages library and nothing else, while your account keeps everything. One housekeeping fact: deleting a user deletes their read progress too, so back out shared accounts rather than recreating them. Collections and read lists are the social layer: collections group related series (a whole saga in one place) and read lists group related books (the docs call them "playlists, but for books"). Between library restrictions, age ratings, and read lists, Komga handles a family library without anyone stepping on anyone else's shelf.

Should You Use Komga or Kavita?

Kavita is the other self-hosted comics server you'll meet, and the diversetechgeek review (updated July 31, 2026) gives the cleanest beginner framing: Komga is the easiest install and setup of the three-way comparison, with cross-device reading progress and an approach the reviewer calls easy to use — on macOS it installs like normal software from a DMG, while Kavita is harder to install there and expects Docker. Kavita's edge is ebook handling and reading experience depth; Komga's weaknesses are exactly what you'd expect from a comics-first server: no first-party app, ebook support that trails Kavita and Calibre-Web, and every book — even a standalone graphic novel — living inside a "series."

The practical rule: comics and manga first — Komga. Ebook-heavy library — look harder at Kavita. Many self-hosters eventually run Komga for comics and keep their novels elsewhere, and there is nothing wrong with that split.

How Does Komga Compare to Jellyfin?

Newcomers often file Komga next to Jellyfin, and the comparison is half right: both are self-hosted media servers you reach through a browser, and both organize files into libraries. But Jellyfin serves video and music — Komga serves books, comics, and manga, full stop. They are siblings, not rivals: a homelab that runs our Jellyfin beginner guide for movies gains a books shelf by adding Komga beside it, with neither replacing the other. The diversetechgeek review makes the same point from the other side: Komga's server is reached through a local IP or localhost, just like Jellyfin, so the access pattern feels familiar the moment you've run one of them.

Can You Run Komga on a Synology NAS?

A komga nas install is one of the most popular ways to run it, and the NAS path is well documented — the mariushosting Synology guide (updated around October 4, 2026) documents the full Portainer stack. Its recipe mounts gotson/komga with a 4 GB memory limit, maps host port 8341 to the container's 25600, runs as the Synology user 1026:100, and places both the config and data folders under docker/komga — with the config folder on the NAS's local volume, honoring the no-network-share rule from the section above. Two NAS-specific notes: set the TZ variable to your timezone so scan schedules make sense, and if you put Komga behind HTTPS, activate WebSocket support on the reverse proxy — the web reader streams pages over it, and without it reading stalls. (The guide was tested on Komga 1.28.1 while 1.29.2 is current as of October 28, 2026; the compose steps are unchanged.) If the reverse proxy part is new to you, our Caddy beginner guide covers the pattern.

What Mistakes Do Beginners Make with Komga?

Sources

Komga 1.29.2 release — GitHub gotson/komga releases API, published October 28, 2026 (jar ~127 MB; page-count fix, KOReader hash fix, OPDS deprecated-method replacement). Docker installation guide — komga.org/docs/installation/docker/ (gotson/komga image, ports 25600:25600, /config and /data volumes, --user 1000:1000, local-filesystem warning for /config, JAVA_TOOL_OPTIONS=-Xmx4g, ~1 GB default heap). Configuration guide — komga.org/docs/installation/configuration/ (application.yml created manually, /config mount, config-dir defaults). Web UI guide — komga.org/docs/guides/webui (default port 25600). Libraries guide — komga.org/docs/guides/libraries (library root rules, scan intervals, cbz/zip/cbr/rar/pdf/epub, analysis options, auto-repair, CBR-to-CBZ auto-conversion, library trash). FAQ — komga.org (first account claims the server; ComicInfo.xml and EPUB metadata import overriding file/folder names). Introduction — komga.org/docs/introduction/ (demo server demo.komga.org, [email protected] / komga-demo; supported formats CBZ, CBR, EPUB, PDF). User accounts guide — komga.org/docs/guides/user-accounts (Administrator/Page Streaming/File Download roles, library restrictions, age-rating and label content restrictions). Readers category — komga.org/docs/category/readers (OPDS v1/v2 compatibility; Komelia, Mihon, Kobo, KOReader, Paperback, Panels; Chunky incompatible with 1.4.0+). First-run registration — olares.com/docs/use-cases/komga, updated October 31, 2026. Media server review: Komga — diversetechgeek.com, updated July 31, 2026 (Komga vs Kavita vs Jellyfin framing, easy install, cross-device progress, weaknesses). Synology install guide — mariushosting.com, updated ~October 4, 2026 (tested 1.28.1; mem_limit 4g, user 1026:100, port 8341:25600, WebSocket requirement for HTTPS). Komga overview — itsfoss.com, crawled November 1, 2026 (multi-user permissions, OPDS feeds, mobile app integration). Panels OPDS piece — Medium, October 26, 2026 (Panels OPDS 1.2 client, page-streaming extension from the Panels team). Komga readers roundup — bookrunch.org, August 7, 2026 (Mihon extension, any-OPDS-reader support, REST API). Tachiyomi integration — dev.to, crawled November 1, 2026 (per-library permissions). XDA review — xda (format list CBZ, CBR, CBT, PDF, EPUB).

Frequently Asked Questions

Is Komga really free?

Yes — Komga is free, open-source software on GitHub under an open license, and the Docker image is free to pull. There is no premium tier inside the server; the only costs are the hardware you run it on and the comics you buy to fill it.

Do I need Docker to run Komga?

No, but Docker is the recommended beginner path. Komga also ships as a plain Java jar (1.29.2 is about 127 MB) and as native apps for Windows, macOS, and Linux — the diversetechgeek review notes it installs on macOS like ordinary software from a DMG. The jar and native apps suit single-machine installs; Docker suits servers.

How much RAM does Komga need?

Komga's Java heap defaults to about 1 GB, which handles small-to-medium libraries. The mariushosting NAS guide caps the container at 4 GB of RAM, and the official docs suggest raising the heap with JAVA_TOOL_OPTIONS=-Xmx4g only for very large libraries. For a few thousand comics, the default is fine.

Can I read Komga on my Kobo or KOReader e-reader?

Yes. Komga publishes OPDS feeds that any OPDS v1/v2 reader can consume, and Kobo devices have native Kobo Sync support while KOReader reads through OPDS. Set up the feed once on the device and your reading progress syncs back to the server.

Komga vs Kavita: which should a manga collector pick?

Either works, but lean Komga if comics and manga are the core of the library — it has the easiest first install, one-click-ish native apps, and mature comic scanning. Lean Kavita if your library is ebook-heavy, since Komga's ebook handling trails behind. The two are different servers with different focuses, not upgrades of each other.