Scanning a library makes Kavita check its folders and sub-folders for new or removed items (books, archive files, etc). If new media is found, it then pulls it into the library.
You can think of scanning as “check for new or changed content”. It is important that you respect the requirements of file layout in order for Kavita to ingest your files.
- First scans are often slow, especially on networked storage. Be patient
- The Kavita Homepage and Library info, will be updated throughout the scan
Kavita will generate a library representation of your files on disk. A Kavita library does not represent exactly your folder structure. Kavita uses filenames, internal metadata, and some limited folder names to parse out the series, volume, chapter, etc from the file and group them.
The scan parses the file names, reads the comic info (if applicable), updates the database with that information, and updates the UI. If the file hasn't been modified since the last time Kavita scanned, it will not do extra processing on the file. If your archives contain metadata, it will override any parsed information from the file.
To understand in depth how Kavita's scan works, go to the scan loop section of this page here.
During the refresh covers task, the same kind of logic applies. This is a heavy task because of the amount of I/O Kavita has to perform and because of the amount of memory it needs to copy images out of the archive and onto the disk. In this task, Kavita doesn't open up any archives if they haven't been modified unless you start a cover refresh from the UI. Even if the archive was modified, if you've locked the cover image by using the UI to upload your own custom cover, the archive will not be opened.
During the analyze files task, Kavita will open epub files and count the number of words per entity. This is I/O and memory intensive. Like other tasks, Kavita employs checks against Last Modified to avoid re-calculation whenever possible. When invoking this task manually from the UI, it will force a recalculation, so be very careful if you use remote storage or a slow server.
Kavita expects all series to be nested in a folder. The ideal layout is:
Library Root ┠── Series Name A │ ┠── Series Name A - v01.cbz │ ⋮ │ ┠── Series Name A - v06.cbz │ ┖── Specials │ ┖── Artbook 1.cbz │ ┖── Series Name B ┠── Series Name B - v01.cbz ⋮ ┠── Series Name B - v06.cbz ┖── Specials ┖── Artbook 1.cbz
This means you can also have:
Library Root ┠── Publisher A │ ┠── Series Name A │ │ ┠── Series Name A - v01.cbz │ │ ⋮ │ │ ┖── Series Name A - v06.cbz │ │ │ ┖── Series Name B │ ┖── Oneshot.cbz │ ┖── Publisher B ┠── Series Name C │ ┠── Series Name C - v01.cbz │ ⋮ │ ┖── Series Name C - v06.cbz │ ┖── Series Name D ┖── Oneshot.cbz
But no files can exist at root level
Library Root /
Series Name v01 Ch.1.cbz
Series cannot be between 2 adjacent folders (aka
Series Name B cannot have something from
Series Name A ). From the library root
Library Root ┠── Series A │ ┖── Series A File 1.cbz ┖── Series B ┖── Series A File 2.cbz
If these rules are followed, you shouldn't have any problems.
In-depth overview on how the scan loop works
.kavitaignorewill be excluded from the scan. See kavitaignore usage
LocalizedSeriestag which allows 2 different names to be merged together automatically. Note: If there are multiple series in one folder with localizedSeries tag, they will group incorrectly. Kavita will log this, but not stop the scan. This is not a valid configuration.
If there are no modifications to folders, Kavita will not scan or process them.
(Added in v0.5.6)
Folder watching lets kavita know when a file has been added or modified in your library and update it in your kavita instance.
Notice an error? Think you can improve this documentation? Edit this Page