Managing your files

Page overview

Naming convention / File Structure

It's important to know how Kavita parses the info from the files, so you can see what you want how you want.

Kavita uses parsing (not folder structure) to determine what is a series and what belongs to each series. Kavita requires that each series be in its folder and that no files are at root level of the library.

Please Read how the new scanner works prior to continuing with this article

Important: When parsing filenames, anything between parenthesis and parenthesis themselves will be removed from the series name.
If you wish to separate series using Series Name (2019), it's advised to change parenthesis to brackets { } and change series name in the UI

Folder and File Structure TOC:

For all types of libraries, Kavita has an override for treating files as Specials.


Kavita treats multiple types of files as "Specials" and will group them in a separate tab in series detail. Special marker (SP) will be removed from the UI title, however is used when ordering.

An entity is considered a special when a series can be parsed out of it, but no volume or chapter information is found:

Library Root
  ┖── Series Name
      ┖── Series Name.cbz

To force a Special status, the filename can include SP01, SP02, etc. This will take the file and force it to be a special:

Library Root
  ┖── Series Name
      ┖── Series Name SP01 Special Name.cbz

Other keywords that are used to mark as special are Specials, Omake, OneShot, Extra, Art Collection, Side Stories:

Library Root
  ┖── Series Name
      ┖── Specials
          ┖── Series Name Omakes SP01.cbz

For it to identify as a special and not as the series from the filename, it will look up towards the library root and attempt to parse the series name from the folder names.
For example:

Library Root
  ┖── Again!!
      ┖── Specials
            ┖── Again The After Story SP01.cbz

Will parse "Again!!" for the Series name and group the file "Again The After Story SP01.cbz" as a special under the series "Again!!"

Additionaly if the file is a .cb* file, you may set this value with the use of ComicInfo metadata using the format tag

Note: Specials will fall back to the folder name for Series name. If you have a different name than the series files, then your special may not properly group.


In order for something to be parsed as having a volume, a volume must be on the filename.

Volume means:

  • v1
  • vol 1
  • vol. 1
  • volume 01
  • Vol 7.5
  • Volume.2000
  • 卷2
  • 册2
  • 2巻
  • t. 2
  • tome 2
  • Additionaly if the file is a .cb* file, you may set this value with the use of ComicInfo metadata using the volume tag


Kavita uses metadata to parse Series Name, Volumes, Chapters, Special Status, etc...

Kavita reads metadata from within your archives (cbz, cbr, c7, cbt) and epub files. If your archives contain metadata, it will override any parsed information from the filename

You can find multiple tools to add metadata under Misc section

General Overview on how Kavita reads certain metadata tags

EPUB Tag Is In ComicInfo Is Equivalent In Kavita
Description Summary Summary
Creators Writer Writers
Pubishers Publisher Publisher
Publication Date Month, Day, Year Release Date
(Release Year for series)
Title Title Chapter Title
Subjects Genre Genres
Tags Tags
AgeRating Age Rating

Comics and Manga

Comics and manga use a ".xml" file at the root of the cbz, cbr, cbt, cb7 files

This file must be named ComicInfo.xml and be at the root of the archive.

The XML schema of this file can be found in the Anansi Project webpage. We support v2.1 (draft).

Note: Kavita currently supports the following custom tags:

  • <LocalizedTitle> : Contains optional localized series name.


EPUB files do not have a ComicInfo.xml, but they do have some limited metadata in the OPF file. See the table above to know what tags do kavita read from the OPF file

!Note: OPF metadata files must be inside the .epub file, or it won't be read.


Tags that will cause specific behaviour in your kavita:

Age Rating

Age rating may vary between different files within a series. The Series will take the highest Age Rating (aka most mature) and use it from the files contained within. So for example, say you have:

Current tags from less restrictive to most restrictive:

  • Issue 1 - PG
  • Issue 2 - PG
  • Issue 3 - M

The series will be M as that is the most mature rating in all Issues.


Kavita will set the Publication Status on a series for you based on this tag

  • If you have at least one "Count" defined within any ComicInfo from the series, and it is not 0, then Kavita will assume the Series is Completed. Otherwise, it will be assumed Ongoing.

  • Ideally, the value of this field should be the total number of volumes (manga) or issues (comics)

Release Year

Likewise with Age Rating, Release Year is a summation of the minimum year defined within a series that is at least 4 units long (> 1000).

Publication Status

Kavita will set the Publication Status on a series for you based on the underlying ComicInfo.

If you have at least one ComicInfo with the Count property, then Kavita will at least mark the series as Ended.

Kavita will also check if the number of Volumes or Chapters matches this exactly and if so, will mark the series as Completed.

This logic will only run if the field is not locked. At any time you can hover over the tag badge in Series Detail to view how many issues or volumes you are missing.


If a Format is specified, that issue or volume may be forced into being treated as a Special (v0.5.4+).

The following entries will cause this:

  • Special
  • Reference
  • Director's Cut
  • Box Set
  • Box-Set
  • Annual
  • Anthology
  • Epilogue
  • One Shot
  • One-Shot
  • Prologue
  • TPB
  • Trade Paper Back
  • Omnibus
  • Compendium
  • Absolute
  • Graphic Novel
  • GN
  • FCBD

Notice an error? Think you can improve this documentation? Edit this Page