# manga-tui reads and downloads manga inside a terminal window

> A Rust terminal application built on ratatui that scrapes three manga providers, renders pages as images in terminals such as Wezterm and Kitty, and downloads chapters as cbz, epub, pdf or raw pages. It works well as a reader, and its provider layer is the fragile part.

**josueBarretogit/manga-tui** — Terminal-based manga reader and downloader with image rendering support 

- Repository: https://github.com/josueBarretogit/manga-tui
- Website: https://crates.io/crates/manga-tui
- Stars: 957 · Forks: 38
- Language: Rust
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/josuebarretogit-manga-tui

## A reader that treats the terminal as the whole interface

manga-tui is a terminal based manga reader and downloader written in Rust, published on crates.io as manga-tui and licensed under MIT. It is a TUI application in the full sense: you launch it, a full screen interface takes over the terminal, and browsing, searching and reading all happen inside that interface rather than in a sequence of shell commands.

The audience is a person who lives in a terminal. That assumption shows up in the dependency set and in the docs. The interface is built on ratatui 0.29.0 with the all-widgets feature set, crossterm 0.29.0 provides the terminal event stream, and throbber-widgets-tui and tui-input handle the spinner and text entry widgets. The search screen supports advanced filtering, and the reading history is stored locally with no login required, which removes the usual friction of setting up an account before you can read anything.

Downloads are a first class feature rather than an afterthought. You can download a single title, or every chapter of a title, and the output can be a cbz archive, an epub, a pdf, or raw images. The epub path is built with the epub-builder crate, the zip crate handles the archive format, and rusqlite with the bundled feature backs the local data storage.

The project is not a thin wrapper around a website. It parses provider pages with the scraper crate and does its own HTTP work with reqwest, with the json, native-tls-alpn, cookies, http2, gzip and deflate features enabled.

## Image rendering is the feature, and the Windows caveat comes with it

The distinguishing technical problem for a manga reader in a terminal is drawing a page. A manga page is a tall, dense image, and a terminal character grid is not a framebuffer. manga-tui delegates that to ratatui-image 1.0.5 with the rustix feature, which is what turns a fetched JPEG or PNG into cells, half blocks or an escape sequence depending on what the terminal can do.

The docs name the terminals that work: Wezterm, iTerm2, Kitty and Ghostty, with a link to a compatibility matrix in the ratatui-image project. The author prefers Wezterm and uses it for the demonstration videos. The general rule is that if your terminal has no image support, no images appear, and the application still runs as a downloader, so the tool degrades rather than fails.

The exception is Windows, where the README carries an explicit warning that image display is very buggy and points at a tracked issue for the details. That is a meaningful boundary for adoption, because on a Windows machine the reading experience that distinguishes this project from a plain scraper is the part that does not work properly. The Linux side has its own dependency wrinkle: the D-bus secret service library, installed as libdbus-1-dev and pkg-config on Debian, dbus-devel and pkgconf-pkg-config on Fedora, or dbus and pkgconf on Arch, because the keyring crate is compiled with the apple-native, windows-native and sync-secret-service features.

So the terminal choice is not cosmetic. It determines whether the core feature works.

## Three providers behind one flag, and a warning that any of them can vanish

manga-tui currently lists Mangadex, Weebcentral and MangaPill as providers, and the reason for having three is stated plainly in the README: if any one goes down you can still use manga-tui. Switching is a command line flag, with mangadex used by default:

```shell
manga-tui -p weebcentral
```

The same provider is also selectable in the config file through default_manga_provider, whose documented values are mangadex, weebcentral and mangapill.

The README is unusually candid about the fragility of this layer, warning readers to expect any provider to fail at some point, whether because the operation closes following a lawsuit or because the provider has issues of its own, with a tracked issue about manganato given as an example of the second case. That warning is the single most important operational fact for anyone considering a daily habit out of this tool.

The design response is redundancy plus persistence. Redundancy comes from the three providers. Persistence comes from the local storage: reading history, bookmarks, downloaded chapters and the config file all live on the machine, so a provider outage costs you the network fetch rather than your library. The auto_bookmark option, true by default, keeps the chapter pointer moving automatically unless you turn it off, and check_new_updates, also on by default, is what tells the app to look for new chapters when you open a title you already follow.

## Installing on Linux with cargo, an AUR helper, Nix or a release binary

There are four documented ways in, and they differ in how much they trust the release process.

Cargo is the most direct, and the --locked flag pins the dependency versions recorded in Cargo.lock:

```shell
cargo install manga-tui --locked
```

Arch users have a published AUR package, installed with an AUR helper:

```shell
paru -S manga-tui
```

Nix users are pointed at the flake in this repository, which builds the latest git version from source rather than a tagged release. Running it without installing:

```sh
nix run 'github:josueBarretogit/manga-tui'
```

Or installing it into the user profile so the command is on the path:

```sh
nix profile install 'github:josueBarretogit/manga-tui'
```

The fourth option is a prebuilt binary from the releases page.

The repository also carries a Dockerfile that shows the build contract. It compiles with a Rust builder stage and copies the release binary into a Debian runtime image, with the terminal environment declared rather than assumed:

```dockerfile
FROM rust:latest as builder
WORKDIR /app
RUN cargo build --release
FROM debian:latest
COPY --from=builder /app/target/release/manga-tui .
ENV TERM=xterm-256color
CMD ["./manga-tui"]
```

That image installs libdbus-1-dev, pkg-config, openssl and libssl-dev, which matches the keyring and TLS features the binary needs. The build in the repository is also driven by rust-toolchain.toml, with bacon.toml, Makefile.toml and a .rusty-hook.toml for the local development loop, and benches/ and data_test/ directories for benchmarks and test data.

## A single config.toml drives download format, quality and tracking

All configuration lives in one file, at XDG_CONFIG_HOME/manga-tui/config.toml, and the application will tell you where that is with:

```shell
manga-tui --config-dir
```

The file is plain TOML with commented defaults, and the keys that matter most at a glance are these:

```toml
download_type = "cbz"
image_quality = "low"
amount_pages = 5
default_manga_provider = "mangadex"
```

download_type accepts cbz, raw, epub or pdf, so the same tool can feed a comic archive reader, a document reader or a plain image folder. image_quality accepts low or high, and the comment notes that low means compressed images, which is the setting to keep on a slow connection. amount_pages is the number of pages around the current one to prefetch, from 0 to 255, and it is the knob that trades bandwidth against page turning latency.

The tracking options are split in a way that has privacy consequences. track_reading_history defaults to true and connects to services such as AniList, while track_reading_when_download defaults to false, so a bulk download does not silently mark a title as read. If you want the AniList credentials to come from the file rather than from an interactive login, the file has an anilist table with client_id and access_token, both empty strings by default, and the comment says to leave them empty if you do not want the config to hold those credentials.

That last point matters because the file is plain text in a config directory, while the keyring dependency suggests the interactive path stores secrets through the platform secret service.

## MIT licensed, published to crates.io, with a repository that moved ahead of its tag

The licence field on the repository says MIT, and Cargo.toml repeats it, so there is no ambiguity about terms for redistribution or for a commercial wrapper.

The release history is the part that deserves attention. The published versions are v0.10.0 on 2025-11-13, v0.9.0 on 2025-08-16 and v0.8.1 on 2025-06-15, and the version in Cargo.toml is still 0.10.0. The last push was on 2026-07-13, and the repository is not archived. The tree has therefore moved a long way past the most recent tag without a new release, and the Nix route, which builds the latest git version, gives you that newer code while the crates.io package gives you 0.10.0.

That gap is a practical upgrade decision rather than a maturity judgement. Anyone who wants the current main branch has to build from source, and anyone who wants a stable package has to accept code that predates the last push. A version bump also means checking the config schema, since keys such as default_manga_provider have documented value lists that can gain entries over time.

The overall shape of the project is a competent single purpose Rust application: one binary, one config file, one dependency on the terminal being able to draw. That narrowness is a strength for anyone who wants a small tool, and a limit for anyone who wanted a general library for manga metadata.

## Conclusion

manga-tui fits a reader who wants a keyboard driven manga browser in a terminal and already uses a terminal that can draw images, and it fits a Linux user who prefers cargo install manga-tui --locked or a Nix flake over a packaged binary. It does not fit someone on Windows who needs reliable page rendering, since the project itself flags image display there as very buggy, and it is a poor choice for unattended bulk downloading because every provider can disappear without notice. Verify first that your terminal renders images at all, by checking whether pages appear rather than placeholders, and read the provider warning in the README before you commit a download habit to one source.

## FAQ

### Does manga-tui require an account to track my reading history?

No. Reading history is stored locally with no login required. The AniList integration is optional and controlled by the track_reading_history and track_reading_when_download settings, with credentials read from the anilist section of the config file if you want them there.

### Which formats can manga-tui download?

The documented formats are cbz, epub, pdf and raw images, selected with the download_type key in the config file, which defaults to cbz. A single title or every chapter of a title can be downloaded.

### Which terminal do I need to read manga in manga-tui?

The documentation names Wezterm, iTerm2, Kitty and Ghostty as terminals that can render images. Without image support no pages are displayed, although the application still works as a downloader, and on Windows image display is described as very buggy.

### Where does manga-tui keep its config and data?

The config file is at XDG_CONFIG_HOME/manga-tui/config.toml, and the application prints the location when you run manga-tui --config-dir. Downloads and reading history are stored in the manga-tui directory.

## Sources

- [josueBarretogit/manga-tui on GitHub](https://github.com/josueBarretogit/manga-tui)
- [License: MIT](https://github.com/josueBarretogit/manga-tui/blob/main/LICENSE)
- [Project website](https://crates.io/crates/manga-tui)
- [README](https://github.com/josueBarretogit/manga-tui/blob/main/README.md)
- [Releases](https://github.com/josueBarretogit/manga-tui/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/josuebarretogit-manga-tui