Kyoo: a self-hosted media server that refuses to care about your folder structure

The problem Kyoo picks: libraries that were never organised in the first place

Most media servers assume you have already done the hard part. You rename files, you build a Movies/Show/Season 02 tree, and you accept that a mislabelled episode becomes a metadata editing session. Kyoo inverts that. The README says no folder structure is required and no manual metadata edits are needed, and it goes further by declaring that media not being scanned correctly, even with weird names, is considered a bug rather than a user error. That is a commitment about where the work sits: inside the scanner, not inside your evening. The target user is someone with a download directory full of inconsistently named releases, or an anime collection where the naming conventions do not map cleanly onto a season-and-episode model. The README explicitly says you could point Kyoo at your download directory and it would work. That is a narrower and more honest pitch than a general-purpose media server. It also tells you who this is not for: if your library is already tidy and you want deep per-item control over artwork and metadata, the automatic behaviour is the thing you will end up fighting.

Multiple services, Postgres instead of SQLite, and a transcoder other projects can borrow

The README describes Kyoo as split into multiple services that can work separately, and states that v5 rewrote most of the code with a relatively low tech depth. The stack is Postgres rather than SQLite, which the README frames as a deliberate server-oriented choice. The practical consequence is that Kyoo is not a single binary you drop on a NAS. It is a set of processes that talk to a database, and the documentation notes that third-party apps can use those services independently, citing Meelo as a project that uses Kyoo's transcoder. That is an unusual posture for a media server: the transcoder is exposed as something closer to infrastructure than to a private implementation detail. Transcoding itself is dynamic, with ABR (automatic quality switching based on network conditions) and the option to serve original quality. Intro and credit detection run either through audio fingerprinting or by matching chapter titles, which is two mechanisms rather than one, and the fallback matters because chapter metadata is frequently absent. Subtitle handling covers PGS and VobSub as well as SSA/ASS, and the README says embedded fonts from the video are used when available, including on web and Chromecast. That last point is where most browser-based players give up, so it is worth verifying on your own files rather than taking on faith.

Getting it running: Docker, a Helm chart, and the switches that actually change behaviour

The README points to INSTALLING.md for basic installation, how to start Kyoo, enabling OIDC, and hardware transcoding. Those are the four things the project treats as configuration rather than defaults. There is no long list of server-wide options, and the README states that plainly as a design goal: few options, setup in about five minutes. OIDC is the authentication path, and the README lists Google, Discord and Authelia as examples of compliant providers, so there is no built-in local account system described in the material. For Kubernetes there is an official Helm chart, and the README adds that multiple replicas are a work in progress, which is a direct warning about horizontal scaling. The API is documented at kyoo.zoriya.dev/swagger, which is the reference to use if you intend to script against it or integrate another service. I have not installed or run Kyoo, so I cannot tell you what the compose file contains or how long a first scan takes. What the material does establish is the shape of the deployment: containers, a Postgres instance, and a set of services you start together. Anything beyond that has to come from INSTALLING.md, which is the document to read before you commit a host to this.

What v5 dropped, and why that should shape your decision

Two features in the README are struck through with the note that they are soon, not reimplemented in v5: watch list scrubbing, which syncs your watched state to services such as SIMKL, and download and offline support, which would let you cache videos and sync progress when a device reconnects. The v5 rewrite bought a cleaner architecture and cost these two features their implementation. That is the most useful fact in the whole repository for anyone evaluating it right now, because both features are the kind that users notice only after they have migrated. If your current setup depends on watched state propagating to a tracking service, Kyoo v5 does not do that yet. If you watch on a tablet on a plane, it does not do that yet either. The README also states that Kyoo has no plugin system and aims to build every feature in. That removes an entire category of community extension, and it means the feature list is effectively the maintainer's roadmap. Combined with the note that the project is developed by one person, the absence of plugins is a concentration of both control and workload in the same place.

Clients: web, Android and Chromecast, with Android TV still on the list

The supported client list is short and partly unchecked. Web, Android and Chromecast are marked done. Android TV is marked as planned, hopefully soon. The README explains the cause directly: the project is developed by one person, so only a few clients exist, and it invites contributions. It also notes that the front end is written in react-native, which makes maintaining additional clients less costly, though adapting the code so the native experience is good still takes time. The Android client uses VLC as its player, with exoplayer available as an alternative, which is a codec-coverage decision rather than a preference. For a household whose main television is an Android TV box, the missing client is the whole question. Chromecast support covers the casting case, but casting is not the same interaction as a native remote-driven interface. This is the clearest example of a gap that the README does not hide. It states the status and the reason. Whether that gap is acceptable depends entirely on which screen you watch on, and there is no way to read around it.

Jellyfin and Plex solve the same problem from the opposite direction

The README names Jellyfin and Plex as the alternatives Kyoo positions itself against, and the difference is not feature count. It is where the configuration burden lands. Jellyfin and Plex both expect a library layout they can parse, and both give you metadata editing tools for when parsing fails. Kyoo's answer is to remove the expectation and treat the failure as its own defect. Plex adds a hosted account layer and a commercial tier on top of that. Jellyfin stays self-hosted and has a plugin ecosystem, which Kyoo deliberately does not. The trade is legible: Jellyfin offers extensibility and a broader client matrix in exchange for you maintaining a folder structure and occasionally correcting a match; Kyoo offers automatic handling of messy input in exchange for a fixed feature set, fewer clients, and a Postgres-backed multi-service deployment. There is also a philosophical difference in scope. The README says the project started before Jellyfin existed and now serves as the author's daily driver, and that the goal is low maintenance rather than maximal capability. If you want a media server you can extend, that goal is not aligned with yours.

Maintenance, licensing, and what GPL-3.0 means for a self-hosted install

Kyoo is GPL-3.0. For someone running it at home, the licence mostly means you receive the source and can modify it. The copyleft terms become relevant if you redistribute a modified version or offer it as a network service to others, and that is a question for a lawyer rather than for this article. On maintenance cost, the README's stated aim is a low amount of upkeep, and the absence of a folder structure to curate is the mechanism behind that claim. The counterweight is operational: Postgres, multiple services, and for Kubernetes users a Helm chart whose multi-replica support is described as a work in progress. Upgrades are the other variable. The release history shows v5.1.0 in July 2026 and v5.2.0 and v5.2.1 in late August 2026, so point releases arrive on a fairly short cadence, and the jump from v4 to v5 was the kind of rewrite that left two features behind. Pin a specific tag rather than tracking master, read the release notes for the version you move to, and check whether the struck-through features have returned before you plan an upgrade around them.

Who should run Kyoo, and what to confirm before you do

Kyoo fits a specific situation: a messy library, a host that already runs Docker or Kubernetes, comfort with Postgres, and a viewing setup centred on web, Android phones or Chromecast. Under those conditions the automatic scanning is the feature you are buying, and the small server-wide option surface is a benefit rather than a limitation. It does not fit a household whose main screen is Android TV, anyone who needs offline playback or watched-state sync to a tracking service in the current v5 line, or anyone who wants to extend their media server through plugins. The verification steps are concrete. Read INSTALLING.md before you touch a host, because that is where OIDC and hardware transcoding are documented. Check the Helm chart's notes on replica count if you plan to run more than one instance. Test the scanner against your worst-named files first, since that is the claim the project stakes itself on and the one most likely to decide the outcome. Then check the release notes for the tag you intend to run to see whether watch-list scrubbing and download support have been reimplemented, because those two struck-through lines are the difference between Kyoo replacing your current server and Kyoo sitting next to it.

Editorial conclusion

Adopt Kyoo if your library is messy, you already run Postgres and Docker or Kubernetes, and you accept a single-maintainer project with a narrow client list. Do not adopt it if you need Android TV today, offline downloads, or an ecosystem of third-party plugins, because the README marks Android TV as planned and both download support and watch-list scrubbing as not reimplemented in v5. Before committing, read INSTALLING.md end to end, confirm which services the compose file starts, and check whether the release you pin still carries those two struck-through features.

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. zoriya/Kyoo on GitHub