comicread

README

comicread 📖

comicread is a lightweight terminal reader for manga, comics, and other image-first books. Written in Go, it opens CBZ, image-based PDF and EPUB files, or directories of images, and lets you read them without leaving the terminal.

When the terminal supports it, pages are displayed as images through the Kitty, Sixel, or iTerm2 graphics protocols. ASCII and Braille-dot renderers provide a usable fallback in ordinary UTF-8 terminals. The interface stays deliberately small: open a chapter, turn pages with the keyboard, and focus on reading.

Features 💫

• Runs on Linux, macOS, and Windows.
• Fast and lightweight — a single standalone binary, no external libraries to install.
• Native application written in Go — no JavaScript runtime, no Node.js, no Electron.
• Reads CBZ, PDF, EPUB files, and image directories.
• Start a local web server and read manga in any browser.
• Renders pages via Kitty, Sixel, or iTerm2, with ASCII/Braille-dot fallback in plain UTF-8 terminals.
• Saves bookmarks and resumes each chapter at its last-opened page.
• Supports single, spread (LTR/RTL), and overlapping-page views.
• Offers keyboard navigation, zoom/scroll, help, and a file picker.
• Localised in 15+ languages.

Installation

Linux and macOS

curl -fsSL https://raw.githubusercontent.com/arimatakao/comicread/main/install.sh | bash

Manual installation or running

Download the archive for your operating system and architecture from the latest release, then extract it.

On Linux or macOS:

tar -xzf comicread_*_linux_*.tar.gz # use *_darwin_* on macOS
./comicread /path/to/file.pdf # or file.cbz / file.epub

Move the extracted executable to a directory in your PATH to install it manually.

Windows

powershell -ExecutionPolicy Bypass -Command "iwr -useb https://raw.githubusercontent.com/arimatakao/comicread/main/install.ps1 | iex"

Manual installation or running

On Windows:

Expand-Archive .\comicread_*_windows_*.zip -DestinationPath .\comicread
.\comicread\comicread.exe C:\path\to\file.pdf # or file.cbz / file.epub

Move the extracted executable to a directory in your PATH to install it manually.

Go

Requires Go 1.26.5 or newer:

go install github.com/arimatakao/comicread@latest

Docker

Clone the repository and enter its directory:

git clone https://github.com/arimatakao/comicread.git
cd comicread

Build the image:

docker build -t comicread .

Run the web reader:

docker run --rm --network host comicread

Then open http://127.0.0.1:55566 in a browser. The web reader currently listens only on localhost, so Docker port publishing (-p 55566:55566) cannot expose it outside the container.

Terminal compatibility

kitty, sixel, and iterm2 render raster images. ascii and dots are text-art fallbacks: they need ANSI cursor control and colour (true colour is recommended); dots also needs Unicode Braille support. The latter two therefore work in virtually every current UTF-8 terminal, including terminals without an image protocol.

Terminal	kitty	sixel	iterm2	ascii	dots	Notes
Any current ANSI/UTF-8 terminal	-	-	-	X	X	Fallback modes; use ascii if Braille glyphs are unavailable.
Alacritty	-	-	-	X	X	No support for these image protocols in the standard build.
Bobcat	-	X	-	X	X	Cross-platform (incl. Windows); natively supports SIXEL.
Cmder	-	-	-	X	X	Built on the ConEmu console; inherits its lack of SIXEL/Kitty support.
ConEmu	-	-	-	X	X	No SIXEL or Kitty graphics protocol support.
Contour	-	X	-	X	X
DomTerm	-	X	-	X	X
foot	-	X	-	X	X
Ghostty	X	-	-	X	X	Kitty graphics protocol.
GNOME Console	-	-	-	X	X	VTE-based; its optional SIXEL support is disabled by default.
GNOME Terminal	-	-	-	X	X	VTE-based; its optional SIXEL support is disabled by default.
Guake	-	-	-	X	X	VTE-based drop-down terminal; SIXEL is disabled by default.
Hyper	-	-	X	X	X	Electron-based terminal; supports the iTerm2 inline image protocol only.
iTerm2	X	X	X	X	X	Supports all three; its release notes document SIXEL and Kitty support.
Kitty	X	-	-	X	X	Native implementation of the Kitty graphics protocol.
Konsole	X	X	X	X	X	iTerm2 support is available since 22.04; animated images are limited.
LXTerminal	-	-	-	X	X	VTE-based; its optional SIXEL support is disabled by default.
MATE Terminal	-	-	-	X	X	Standard MATE terminal; no image protocol support.
mintty / wsltty	-	X	X	X	X	Windows/Cygwin terminal and its WSL variant.
mlterm	-	X	X	X	X	iterm2 requires a build with SUPPORT_ITERM2_OSC1337.
MobaXterm	-	-	-	X	X	No SIXEL or Kitty graphics protocol support found in its release notes.
Ptyxis	-	-	-	X	X	GNOME container-focused terminal; no raster image protocol support yet.
PuTTY	-	-	-	X	X	No SIXEL or Kitty graphics protocol support.
QTerminal	-	-	-	X	X	LXQt terminal based on qtermwidget; no SIXEL or Kitty support yet.
Rio	X	X	X	X	X	Supports Kitty, Sixel, and iTerm2 image protocols.
st with a graphics patch	X	-	-	X	X	Requires a Kitty-graphics implementation patch.
SyncTERM	-	X	-	X	X
Tabby	-	X	-	X	X	SIXEL only; Kitty graphics protocol support is still an open request.
Terminator	-	-	-	X	X	VTE-based; its optional SIXEL support is disabled by default.
Tilix	-	-	-	X	X	VTE-based; its optional SIXEL support is disabled by default.
Warp	X	-	-	X	X	Implements the Kitty graphics protocol.
wayst	X	X	-	X	X	Kitty graphics protocol; SIXEL support is experimental.
WezTerm	X	X	X	X	X	Enable enable_kitty_graphics=true for kitty; Sixel is experimental.
Windows Terminal	-	X	-	X	X	SIXEL support added in 1.22; no Kitty graphics protocol support yet.
Xfce Terminal	-	-	-	X	X	VTE-based; its optional SIXEL support is disabled by default.
xterm	-	X	-	X	X	Must be built with SIXEL and configured as a DEC graphics terminal.
xterm.js host	X	X	X	X	X	Requires the image add-on; its Kitty implementation is partial.
yaft	-	X	-	X	X	Linux framebuffer terminal.
Yakuake	X	X	X	X	X	KDE drop-down terminal built on the Konsole KPart; inherits its graphics support.

Basic usage

# Open the file picker and choose a file.
comicread

# Show the command help.
comicread --help

# Print the version or check for available updates.
comicread --version
comicread --update

# Open the interactive file picker in the current directory.
comicread

# Open the interactive file picker in a specific directory.
comicread --open /path/to/manga

# Ignore the configured directory and open the file picker in the current directory.
comicread --open

# Start the local browser-based reader.
comicread --web

# Read a CBZ archive.
comicread /path/to/file.cbz

# Read an image-based PDF or EPUB.
comicread /path/to/file.pdf
comicread /path/to/file.epub

# Read images from a directory.
comicread /path/to/image-directory

# Use the Kitty, Sixel, or iTerm2 image protocol explicitly.
comicread --graphics kitty /path/to/file.cbz
comicread --graphics sixel /path/to/file.cbz
comicread --graphics iterm2 /path/to/file.cbz

# Use text-art renderers when the terminal has no image protocol.
comicread --graphics ascii /path/to/file.cbz
comicread --graphics dots /path/to/file.cbz

# Combine an explicit renderer with a right-to-left page layout.
comicread --graphics sixel --right-view /path/to/file.cbz

# Show page pairs left to right or right to left.
comicread --book-view /path/to/file.cbz
comicread --right-view /path/to/file.cbz

# Show overlapping page pairs left to right or right to left.
comicread --circle-view /path/to/file.cbz
comicread --right-circle-view /path/to/file.cbz

# Remove saved reading progress and bookmarks for a file or directory.
comicread --clear-journal /path/to/file.cbz
comicread --clear-journal /path/to/image-directory

# Use a config file at a specific path instead of the default location.
comicread --config /path/to/config.toml /path/to/file.cbz

# Set one config option (key=value) in the default config file and exit.
comicread --set-config graphics=sixel
comicread --set-config prerender.next=2

# Set a config option in a specific config file and exit.
comicread --config /path/to/config.toml --set-config view=right-view

# Reset the default config file to its defaults.
comicread --reset-config

# Reset a specific config file to its defaults.
comicread --config /path/to/config.toml --reset-config

Configuration file

comicread reads defaults from a config.toml file. See config-example.toml for the full list of options and their defaults, and copy it to the platform configuration directory to use it:

• Linux: ~/.config/comicread/config.toml
• macOS: ~/Library/Application Support/comicread/config.toml
• Windows: %AppData%\comicread\config.toml

Use --config to point at a different file, --set-config key=value to update a single option in place, and --reset-config to restore defaults.

Supported language codes:

Code	Language
en	English
uk	Ukrainian
pl	Polish
de	German
fr	French
es	Spanish
cs	Czech
ro	Romanian
it	Italian
ko	Korean
ja	Japanese
id	Indonesian
hi	Hindi
el	Greek
tr	Turkish
kk	Kazakh
ka	Georgian
hu	Hungarian
sv	Swedish
no	Norwegian
da	Danish
fi	Finnish

Controls

Reader

Keys	Action
right, l, space, j, PageDown	Next page
left, h, backspace, k, PageUp	Previous page
+, -	Zoom in or out
up, down	Scroll a zoomed page
b	Add or remove a bookmark on the current page
v then left or right	Go to the previous or next bookmark
c then v	Open the bookmark list
g then digits, Enter	Go to a page number (Esc cancels)
?	Open or close help
q, Esc, Ctrl+C	Quit

Bookmark list

Keys	Action
up, down	Move selection
Enter	Open the selected bookmark
q, Esc	Close the list

File picker

Keys	Action
up, k, down, j	Move selection
left, h	Open the parent directory
right, l	Enter the selected directory
Enter	Open the selected file
s	Open the selected directory
o	Enter a directory path
: then g and a path, Enter	Go to a directory path
f	Add or remove the current directory from favorites
F	Add a directory path to favorites
b	Open the favorites list
q, Esc, Ctrl+C	Quit

Favorites list

Keys	Action
up, k, down, j	Move selection
Enter, right, l	Open the selected directory
d	Remove the selected directory from favorites
f, Esc	Close the list
q, Ctrl+C	Quit

Dependency licenses

The main direct dependencies are distributed under permissive licenses:

• Bubble Tea v2 — MIT
• rasterm — MIT
• comicfile — MIT
• ASCIIimage v2 — MIT
• dots — Apache License 2.0
• go-toml v2 — MIT
• golang.org/x/image — BSD-style (Go Authors)
• Pico CSS — MIT

See the LICENSE file bundled with each dependency version in the Go module cache for its full license text. Transitive dependencies may have their own license terms.