Suwayomi-Server Documentation

Suwayomi is a free and open-source manga reader server that runs extensions built for Mihon (Tachiyomi). It is an independent software and not a fork of Mihon. It is multi-platform, running on any system that supports Java and a modern browser (Windows, Linux, macOS, Chrome OS, etc.).

Key Features:

• Executes Mihon (Tachiyomi) extensions.
• Library management (save manga/categories) and automated updates/downloads.
• Offline reading support.
• Backup and restore via Mihon-compatible formats.
• Tracking integration (MyAnimeList, AniList, MangaUpdates, etc.).
• FlareSolverr support for Cloudflare bypass.
• OPDS and OPDS-PSE support (endpoint: /api/opds/v1.2).

Suwayomi-Server requires a client or user interface to function. If you download the bundled version from the releases page, it includes Suwayomi-WebUI.

Integrated Clients (Built-in/Auto-updated):

• Suwayomi-WebUI: Web app, PWA.
• Suwayomi-VUI: Web app, PWA.

Other Clients (May be inactive/abandoned):

• Tachidesk-VaadinUI: Desktop app (Windows, Linux, macOS).
• Moku: Desktop app (Windows, Linux, macOS).
• Tachidesk-JUI: Desktop app (Windows, Linux, macOS).
• Tachidesk-Sorayomi: Web app, Desktop app, and Android app.
• Tachidesk-qtui: Android, iOS, and Linux desktop app.
• Suwayomi Client for KOReader: KOReader plugin (Android, Kindle, Kobo, etc.).

The default data directory for Suwayomi depends on your operating system. Replace <Account> with your actual account or username.

• Windows 7 and later: C:\Users\<Account>\AppData\Local\Tachidesk
• Windows XP: C:\Documents and Settings\<Account>\Application Data\Local Settings\Tachidesk
• macOS: /Users/<Account>/Library/Application Support/Tachidesk
• Unix/Linux: /home/<account>/.local/share/Tachidesk

Suwayomi-Server does not include default extensions. You must manually provide a Tachiyomi extension repository URL. Valid repository formats include:

• https://raw.githubusercontent.com/user/reponame
• https://www.github.com/user/reponame

You can configure these repositories using one of the following four methods depending on your installation type:

You can run Suwayomi Server in a container using the Official Docker release Suwayomi Container.

By default, the server runs on http://localhost:4567. You can find example compose files in the docker-tachidesk repository.

When running Suwayomi in a headless environment where no GUI or browser is available, you must disable system tray and browser automation in server.conf to prevent errors:

• Set server.systemTrayEnabled to false to prevent attempts to create a System Tray icon.
• Set server.initialOpenInBrowserEnabled to false to prevent attempts to open a web browser on startup.

The default Data Directory path can only be changed using a command-line argument. Use the special configuration option server.rootDir passed as a Java system property to specify a custom location for your data directory.

java -Dsuwayomi.tachidesk.config.server.rootDir="/path/to/data/directory" -jar Suwayomi-Server-v0.X.Y-rXXXX.jar

You can add extended metadata (author, artist, description, genres) to local manga by creating a JSON file inside the manga's root folder. While the file can be named anything, it is standard to name it details.json.

Once the file is added, the app will load the data when you first open the manga, or you can refresh the details manually.

JSON Schema Example:

{
	"title": "Example Title",
	"author": "Example Author",
	"artist": "Example Artist",
	"description": "Example Description",
	"genre": ["genre 1", "genre 2", "etc"],
	"status": "0",
	"_status values": ["0 = Unknown", "1 = Ongoing", "2 = Completed", "3 = Licensed"]
}

Install Suwayomi from the AUR using yay:

yay -S suwayomi-server-bin

To run the server directly from a JAR file, ensure you have the following requirements:

• The Suwayomi-Server .jar release (available from the GitHub releases section or preview repository).
• Java Runtime Environment (JRE) 21 or newer.
• A web browser (Chrome, Firefox, Edge, etc.).
• ElectronJS (optional).

To start the application, double-click the .jar file or execute the following command in a Terminal or Command Prompt:

java -jar Suwayomi-Server-vX.Y.Z-rxxxx.jar

Download the appropriate release from the GitHub releases section:

• macOS-x64 for older macOS systems.
• macOS-arm64 for Apple M1 and newer chips.

Unzip the downloaded file and double-click one of the launcher scripts to run.