Skip to content

Shoko File Structure & Import Workflow

How to organize anime files for Shoko Server, including the drop folder workflow, AniDB matching, and Jellyfin/Shokofin integration.

Overview

Shoko identifies files by computing ED2K hashes and matching them against AniDB's database. This means file names and folder structure do not matter for recognition — only the file's binary content matters.

However, your folder structure still matters for:

  • Your own organization and sanity
  • Downstream media servers (Jellyfin, Plex) if not using Shokofin VFS

Drop Folder Workflow

Shoko has a configurable drop folder system with two folder types:

Type DropFolderType Behavior
Drop Source 0 Shoko picks up files from here and moves them to the destination
Drop Destination 1 Where organized/matched files live permanently

How it works

  1. Configure a Drop Source folder (e.g., /drop) for new downloads
  2. Configure a Drop Destination folder (e.g., /anime) for your library
  3. Enable Watch For New Files on the source folder
  4. Drop new anime files into /drop
  5. Shoko hashes the file, matches it against AniDB, and moves it to /anime automatically

Where do files end up?

When a file is moved from the drop source to the destination, Shoko places it based on the matched AniDB entry. With the default renamer:

/drop/random_filename.mkv
  → /anime/Jujutsu Kaisen/Jujutsu Kaisen - 01.mkv

Shoko creates the series folder automatically if it doesn't exist. If Rename on Import is enabled, the file is renamed to match the AniDB episode title. If disabled, the original filename is kept but the file is still moved into the correct series folder.

Non-video files

Shoko only processes video files (.mkv, .avi, .mp4, .ogm, etc.). Non-video files like .txt, .nfo, .jpg, and other unrelated files are ignored — they won't be hashed, matched, or moved. If you drop a .txt alongside a .mkv in the drop source, only the video file gets picked up and moved; the .txt stays behind.

Import Settings

Setting What it does
Import on Start Process any pending files when Shoko launches
Rename on Import Rename files using the configured renamer
Move on Import Move files from source to destination folder
Move After Rename Rename first, then move

Important: Move on Import is disabled by default. Without it, Shoko will match and index files in the drop folder but leave them there. Enable it in the Shoko web UI under Settings > Import, or via the API:

curl -sf -X PATCH "http://<shoko-ip>:8111/api/v3/Settings" \
  -H "apikey: <your-api-key>" \
  -H "Content-Type: application/json-patch+json" \
  -d '[
    {"op": "replace", "path": "/Import/MoveOnImport", "value": true},
    {"op": "replace", "path": "/Import/RenameOnImport", "value": true}
  ]'

Shoko recommends a flat structure — one folder per AniDB entry, all at the same level. Do NOT use nested Season 1/ Season 2/ subfolders.

Correct (flat)

/anime/
  Jujutsu Kaisen/
    episode01.mkv
    episode02.mkv
  Jujutsu Kaisen (2023)/
    episode01.mkv
  Jujutsu Kaisen 0/
    movie.mkv
  Bocchi the Rock!/
    episode01.mkv
  Bocchi the Rock! Recap/
    recap.mkv

Wrong (nested seasons)

/anime/
  Jujutsu Kaisen/
    Season 1/
      episode01.mkv
    Season 2/
      episode01.mkv
    Movie/
      movie.mkv

Why flat?

AniDB treats each season, special, OVA, ONA, and movie as a separate entry with its own ID. Shoko follows this model. "Season 2" of an anime is not a subfolder — it's a completely different AniDB series.

AniDB Matching

  • File names are irrelevant — Shoko hashes the entire file (ED2K) and looks up the hash in AniDB
  • If the hash exists in AniDB, the file is matched automatically regardless of its name
  • If the hash is NOT in AniDB (unrecognized file), you have three options:
  • AVDump the file to AniDB (adds the hash to their database)
  • Manual Link — associate the file with a series/episode in the Shoko web UI
  • Ignore the file

Renamer (WebAOM)

Shoko includes a built-in renamer that can organize files automatically after matching:

Default output: 

/anime/
  Anime Title/
    Anime Title - 01.mkv

With Group Aware Sorting: 

/anime/
  Group Name/
    Anime Title/
      Anime Title - 01.mkv

The renamer runs on import if enabled, using the metadata from AniDB to generate clean filenames.

Jellyfin Integration (Shokofin)

If using Jellyfin with the Shokofin plugin:

  • VFS mode (recommended): Shokofin creates virtual symlinks that satisfy Jellyfin's expected folder structure automatically. Your actual disk layout becomes irrelevant.
  • Without VFS: You must ensure each AniDB series is in a separate folder, and filenames should be parseable (e.g., Jujutsu Kaisen (2023) - 01.mkv).

Docker Volume Mapping

volumes:
  - ./shoko-config:/home/shoko/.shoko   # persistent config (SQLite DB)
  - /path/to/anime:/anime                # library (drop destination)
  - /path/to/drop:/drop                  # drop source for new files

Permissions

The anime and drop directories must be owned by the PUID/PGID specified in the container's environment variables. If the directories are owned by root but the container runs as PUID 1000, Shoko will fail to move files with "Access denied."

# Match ownership to PUID=1000, PGID=100 (default)
chown -R 1000:100 /path/to/anime /path/to/drop

If you see files getting matched and indexed but not moved, check ownership first — this is the most common cause.

References