Skip to content
Media server for comics/mangas/BDs with API and OPDS support
Kotlin Vue TypeScript TSQL JavaScript HTML Other
Branch: master
Clone or download
Latest commit f046bab Jan 21, 2020
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Update issue templates Jan 21, 2020
.idea/runConfigurations add run configurations Aug 20, 2019
.travis ci: don't push to docker if the webui cannot be built Jan 4, 2020
doc/sample-configuration docs: documentation for remember-me functionality Jan 16, 2020
gradle/wrapper update gradle to 5.6.4 Nov 15, 2019
komga-webui feat(webui): add Media Analysis screen showing all books in error Jan 17, 2020
komga revert: revert thumbnails library Jan 18, 2020
res add logo with text as path for proper display in browser Oct 8, 2019
.editorconfig build: add .editorconfig Jan 6, 2020
.gitignore chore: update gitignore Dec 31, 2019
.travis.yml ci: build web app only if a release will happen Dec 31, 2019 chore(release): 0.13.1 [skip ci] Jan 18, 2020 docs: documentation for remember-me functionality Jan 16, 2020
LICENSE Create LICENSE Aug 21, 2019 docs(readme): fix typo on environment variables Jan 16, 2020
build.gradle.kts update gradle to 5.6.4 Nov 15, 2019
cc_defaults.json chore(release): 0.13.1 [skip ci] Jan 18, 2020
gradlew support for multiple libraries Sep 27, 2019
gradlew.bat gradle update to 5.5.1 Aug 24, 2019
package-lock.json chore: add tooling for conventional commits Dec 31, 2019
settings.gradle initial commit Aug 8, 2019

Build Status GitHub release (latest SemVer) Docker Pulls

app icon Komga

Komga is a free and open source comics/mangas server.


Features include:

  • scan and index libraries (local folders) containing sub-folders with comic book archives in cbz and cbr format, as well as pdf. Rescan periodically.
  • API to serve the individual pages of those books. It can convert pages to different image format on the fly.
  • API to serve the complete file for download
  • OPDS feed
  • web interface
  • web reader
  • user management, with per-library access control



The easiest way to run Komga is via Docker. Please refer to the (instructions on how to use the image).

Jar file

Alternatively you can run it from the fat jar file. You can find them in the releases section.

In order to run Komga, use the following command:

java -jar komga-x.y.z.jar

Note that you need to have a valid application.yml configuration file (or environment variables) for Komga to run properly, read on to the next section to find out more.


Komga relies heavily on Spring Boot's configuration, leveraging profiles and configuration properties.

The easiest way to configure is either via environment variables (a good fit for docker-compose) or by using an application.yml file located in the same folder as the jar file.

You can check sample application.yml files for Windows and Unix/Linux.

Each configuration key can have a different format depending if it's from the environment variable, or from the application.yml file. In the following section I will provide both format in the form ENVIRONMENT_VARIABLE / application-property.

Mandatory configuration

In order to make Komga run, you need to specify some mandatory configuration keys (unless you use Docker, in which case defaults are setup):

  • SPRING_PROFILES_ACTIVE / prod - this will enable the database management and upgrades for new versions.
  • SPRING_DATASOURCE_URL / spring.datasource.url: the path of the database file. For Docker I use jdbc:h2:/config/database.h2, where /config/database.h2 is the actual file inside the docker container. You can customize this part if running without docker.

Optional configuration

You can also use some optional configuration keys:

  • KOMGA_LIBRARIES_SCAN_CRON / komga.libraries-scan-cron: a Spring cron expression for libraries periodic rescans. 0 0 * * * ? will rescan every hour. 0 */15 * * * ? will rescan every 15 minutes. Defaults to 0 */15 * * * ? in prod profile.
  • KOMGA_THREADS_ANALYZER / komga.threads.analyzer: the number of worker threads used for analyzing books. Defaults to 2. You can experiment to get better performance.
  • KOMGA_LIBRARIES_SCAN_DIRECTORY_EXCLUSIONS / komga.libraries-scan-directory-exclusions: a list of patterns to exclude directories from the scan. If the full path contains any of the patterns, the directory will be ignored. If using the environment variable form use a comma-separated list.
  • KOMGA_FILESYSTEM_SCANNER_FORCE_DIRECTORY_MODIFIED_TIME / komga.filesystem-scanner-force-directory-modified-time: if set to true, it will force the last modified time of a directory as the maximum from its own last modified time and the last modified time from all the books inside the directory. This should be used only if your filesystem does not update the last modified time of a directory when files inside it are modified (Google Drive for instance).
  • KOMGA_REMEMBERME_KEY / komga.remember-me.key: a unique key. If set, the remember-me auto-login feature will be activated, and will generate a cookie with encoded login information to perform auto-login.
  • KOMGA_REMEMBERME_VALIDITY / komga.remember-me.validity: the validity, in seconds, of the generated remember-me cookie. Defaults to 2 weeks.

What does it do?

Komga will scan your libraries for directories containing supported files (at the moment cbz, zip, cbr, rar and pdf):

  • each folder containing comic books will be made as a Series
  • each comic book file inside a Series will be made as a Book

It works with sub-folders too, so if you have a structure like this:

├── Private Eye/
│   ├── Volume 1.cbz
│   └── Volume 2.cbz
└── One Shot.cbz

Komga will generate:

  • a Series called Comics, containing a Book called One Shot
  • a Series called Private Eye, containing two Books called Volume 1 and Volume 2

On rescans, Komga will update Series and Books, add new ones, and remove the ones for which files don't exist anymore.

Then it will analyze each book, which consist of indexing pages (images in the archive), and generating a thumbnail.


User accounts

At startup, if no user account exists in database, Komga will generate an initial administrator account with a random password, and will output the login and password in the logs:

2019-10-15 17:15:31.483  INFO 18808 --- [  restartedMain] o.g.k.i.scheduler.InitialUserController  : Initial user created. Login:, Password: 2Qf8l85xOB8o

❗️ It is strongly advised to create your own account, and delete the generated account!


If you want to open your Komga server outside your local network, it is strongly advised to secure it with https (especially due to the use of http basic authentication).

Spring Boot supports https out of the box, but you will have to configure it, and https is most useful only with valid certificates (not self-signed), which most people don't readily have available.

I recommend using Caddy as a reverse proxy, as it supports the automatic generation of Let's Encrypt certificates.



Komga has an official extension for Tachiyomi, available from within Tachiyomi's extension menu. The extension is configurable, you need to specify the server address, username, and password.

tachiyomi extension configuration screenshot

OPDS readers

Komga should work with any OPDS reader, unfortunately most readers badly implement the OPDS protocol 😞.

Here is a list of reader applications I have tested:

OS App name Status OpenSearch support Page streaming support
Android FBReader: Favorite Book Reader Can't download CBR/CBZ, only PDF. PDF only supported in Premium version. Does not remember password. No No
Android Moon+ reader Cannot download files. Does not remember password. No No
Android Librera ✔️ No No
Android PocketBook Doesn't show CBR/CBZ No No
iOS KyBook 3 ✔️ Yes No
iOS Chunky Comic Reader ✔️ No Yes

Feel free to report your findings with other readers (by sending a PR)!

Web interface

The web interface is available on port 8080.


  • browse libraries, series, and books
  • search series and books
  • download book file
  • add and remove libraries (for administrators only)
  • server settings (for administrators only)
    • users management (add and remove user, edit user's shared libraries access)
  • account settings
    • change password


Home page Browse Series
webui_screenshot webui-settings-users_screenshot
Web reader Web reader menu
webreader_screenshot webreader-menu_screenshot
Account settings Users management User rights
webui-settings-users_screenshot webui-settings-users_screenshot webui-settings-users_screenshot


Default port for APIs is 8080.

Native API

Komga offers a REST API, which you can browse using Swagger. It's available at /swagger-ui.html. The API offers file download and page streaming.

In order to access the API, you will need to authenticate using Basic Authentication.


Komga offers a standard OPDS feed, it is available at /opds/v1.2/catalog.

The OPDS feed also supports:


The Komga icon is based on an icon made by Freepik from

You can’t perform that action at this time.