Skip to content

Configuration ​

AniWorld Downloader loads startup settings from .env and the process environment:

SystemLocation
Linux and macOS~/.aniworld/.env
Windows%USERPROFILE%\.aniworld\.env

These are the default locations; ANIWORLD_INSTALL_FOLDER can select another app directory. The file is created on first start. Use one NAME=value setting per line and restart the app after editing it.

dotenv
ANIWORLD_LANGUAGE="German Dub"
ANIWORLD_PROVIDER=VOE
ANIWORLD_DOWNLOAD_PATH=Downloads

What survives a restart ​

DataStoragePersists?
Most general settings changed in the Web UIRunning processNo; save their environment values
Startup settings.env or deployment environmentYes
Users, API keys, custom paths, queue records, Auto-Sync exclusionsaniworld.dbYes
Discord settings saved in the Web UI.envYes
Custom CSS and shadercustom.css, custom.fragYes

Settings → Administration → Export settings downloads the configurable Web UI settings as an .env file; it is not a complete export of every startup variable. Secrets such as the Discord token, OIDC secret, and administrator password are omitted; keep those values when merging the export into your existing configuration.

AniWorld settings use the ANIWORLD_ prefix. The MangaFire format setting is ANIWORLD_MANGAFIRE_FORMAT; the .env loader maps a saved MANGAFIRE_FORMAT value to that setting when the prefixed key is absent. OS and dependency variables such as PATH, DISPLAY, XDG_CONFIG_HOME, XDG_CACHE_HOME, APPDATA, LOCALAPPDATA, PLAYWRIGHT_BROWSERS_PATH, PLAYWRIGHT_NODEJS_PATH, SSL_CERT_FILE, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE, and WERKZEUG_RUN_MAIN keep the names required by those systems. They are not AniWorld settings.

At startup the app rewrites .env from its bundled template, retaining existing values for template keys and the three CA variables. Other keys and custom comments are removed. Set dependency variables such as PLAYWRIGHT_BROWSERS_PATH in the process or container environment instead of relying on the app .env to retain them.

Certificate bundle paths can be set in the process environment or the app .env. The process environment wins for the same variable, and the three CA variables survive .env template updates. At startup, each explicit CA path expands a leading ~; ordinary relative paths stay relative to the working directory. The first nonempty value in REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE, then SSL_CERT_FILE order supplies the shared HTTP session's bundle and defaults for unset CA variables; otherwise certifi supplies the bundle. Different explicit bundle choices are preserved, so clients can intentionally use different trust settings. The app keeps the original .env values and expands paths in the running process. Setting only SSL_CERT_FILE also supplies the Requests/cURL defaults. These settings do not configure Chromium's trust store or guarantee that external tools such as FFmpeg, mpv, or Syncplay use that bundle.

Existing process environment variables override values loaded from .env. CLI options override the corresponding settings for that invocation. --output and --episode-file expand ~, including when the argument is quoted; relative CLI paths use the current working directory. All backend models expand ~ and resolve relative ANIWORLD_DOWNLOAD_PATH or Python selected_path values beneath your home directory. Surrounding whitespace is trimmed from ANIWORLD_DOWNLOAD_PATH; spaces in an explicit Python path are preserved. An unset or blank download setting defaults to ~/Downloads. MangaFire's explicit Python file/folder arguments also expand ~ and remain direct destinations, with ordinary relative paths based on the working directory. Explicit paths passed to archive, Anime4K, HLS, .env, download-check and template-root helpers follow the same rule. Only a leading home shortcut expands; ~ inside a filename remains literal. Restart after editing startup configuration.

MangaFire single-page downloads inherit their chapter's selected root when no explicit folder is passed. Chapters, pages and archives use the manga title for the enclosing folder; see the Python API for chapter URLs and destination options.

Set ANIWORLD_INSTALL_FOLDER before launch to use another app data directory. Empty or whitespace-only values use the default app directory. Relative values are resolved against your home directory. On first relocation, the app can copy the old .env; it does not migrate the database or theme files. Move those separately with the app stopped if you want to retain them.

External tool directories ​

AniWorld places AniSkip scripts and Anime4K configuration beneath the mpv configuration directory. Its default Chromium setup selects a separate browser cache:

FilesWindowsmacOSLinux
mpv configuration%APPDATA%/mpv$XDG_CONFIG_HOME/mpv, default ~/.config/mpv$XDG_CONFIG_HOME/mpv, default ~/.config/mpv
Chromium binaries%LOCALAPPDATA%/ms-playwright~/Library/Caches/ms-playwright$XDG_CACHE_HOME/ms-playwright, default ~/.cache/ms-playwright

APPDATA, LOCALAPPDATA, XDG_CONFIG_HOME, and XDG_CACHE_HOME must contain absolute paths. Missing, blank, or relative values use the platform default. On Windows, the app-data fallbacks are ~/AppData/Roaming and ~/AppData/Local. A literal ~/... is relative in these OS variables; use an absolute path or expand $HOME in the shell. When a nonempty XDG_CONFIG_HOME is invalid, AniWorld replaces it with the default in its running process so older mpv builds read the same directory. Explicit PLAYWRIGHT_BROWSERS_PATH and PLAYWRIGHT_NODEJS_PATH values are passed through to Patchright without home expansion; use absolute paths there, or keep PLAYWRIGHT_BROWSERS_PATH=0 for its special package-local mode.

Use the same PLAYWRIGHT_BROWSERS_PATH and PLAYWRIGHT_NODEJS_PATH values when installing Chromium manually and running the app.

Everyday settings ​

SettingDefaultPurpose
ANIWORLD_DOWNLOAD_PATHDownloadsDownload folder, relative to your home folder or absolute
ANIWORLD_LANGUAGEGerman DubGerman Dub, English Sub, German Sub, or English Dub
ANIWORLD_PROVIDERVOEPreferred stream host
ANIWORLD_PROVIDER_FALLBACK_ORDERVOE,Vidmoly,Vidoza,DoodstreamHosts to try when the preferred one fails
ANIWORLD_UI_LANGUAGEenWeb UI language: en or de
ANIWORLD_LANG_SEPARATION0Put Web UI queue downloads into language folders
ANIWORLD_DISABLE_ENGLISH_SUB0Hide English Sub choices and reject them in Web UI/API submissions
ANIWORLD_SHOW_ALL_LANGUAGES0Offer every preset for the site instead of restricting choices to the first-episode probe
ANIWORLD_MOVIE_FOLDER1Put movie-oriented backend downloads in their own title folders
ANIWORLD_VIDEO_CODECcopyCopy streams, or encode using a supported software/hardware codec
ANIWORLD_MANGAFIRE_FORMATjpgjpg, cbz, or epub (requires aniworld[epub]); see manga usage
ANIWORLD_NO_AUTO_INSTALL0Disable automatic dependency downloads and installs, including promptless helper downloads and browser installation
ANIWORLD_HLS_CONCURRENCY8Parallel HLS segments, from 1 to 32
ANIWORLD_DEBUG_MODE0Enable detailed logging
ANIWORLD_NO_MENU0Skip the CLI menu; supply URLs or an episode file
ANIWORLD_MENU_DOWNLOAD_ONLY0, Docker image uses 1Hide Watch and Syncplay in the terminal menu, independently of the download folder
ANIWORLD_ENABLE_LIBRARY1Show the Web UI Library tab

Boolean values use 1 for on and 0 for off.

The fallback order is a preference list, not a host allowlist. Recognized providers omitted from it are appended automatically, and only providers available for the episode and selected language are tried.

ANIWORLD_NO_AUTO_INSTALL=1 skips portable release lookup and automatic dependency downloads and installs. Existing tools on PATH or in the dependency folder remain usable. Cached archives with a known download URL can still be unpacked locally, but 7z archives require an already installed unpacker. This is not a network-offline mode: normal site and media requests still use the network.

Language separation is applied through the Web UI queue path resolver, including Discord requests; direct CLI/Python downloads do not use that resolver. The English Sub restriction is not enforced by direct CLI/Python downloads, Discord requests, or Auto-Sync, and does not apply to the fixed-language HentaiTV/HentaiHaven backends.

File names ​

The default naming template is:

dotenv
ANIWORLD_NAMING_TEMPLATE="{title} ({year}) [imdbid-{imdbid}]/Season {season}/{title} S{season}E{episode}.mkv"

Available placeholders are {title}, {year}, {imdbid}, {season}, {episode}, {resolution}, and {language}. AniWorld, SerienStream, Hanime, MegaKino, Moflix, HentaiTV, AnimeIDHentai, and HentaiHaven can fill {resolution} from the finished file; it falls back to unknown when there is not exactly one video stream. Kinox, BurningSeries, FilmPalast, and Filmo use fixed filename patterns and do not apply the resolution placeholder. Use brace placeholders throughout the template; legacy %title% placeholders are only translated by some filename formatters, not consistently in folder names. The file extension controls the output container. The Web UI's MKV/MP4 setting changes that extension in the running naming template; persist the template to keep it across restarts.

For AniWorld and SerienStream, {episode} uses an explicit [Episode N] or [JP Episode N] marker from the English episode title. A title consisting of Episode N or JP Episode N is also accepted. Numbering is independent of the selected audio language; a title without an unambiguous positive marker uses the episode's index within the season. Season numbers come from the source: One Piece season 2, episode 1 uses S02E062 with the default template. AniWorld film URLs use their film index in season 00 through the episode naming template. Other backends use their own numbering. The Python models expose the seasonal index as season_episode_number; episode_number supplies generated filenames and Web UI episode labels.

An existing download at the seasonal path is reused when the template, destination, language and extension still match. Files are not automatically renamed. Library badges and Auto-Sync recognise both numbering schemes, including four-digit episode numbers. Downloads store the source episode URL in a global container comment tag with the value aniworld_episode_url=<episode URL>. Detection uses that URL before the filename, including when AniWorld and SerienStream share a library. Source matching keeps backends separate and accepts SerienStream domain aliases. An output path assigned to a different source episode raises a conflict and retains the existing file. If a file has an ambiguous number and no matching source metadata, the operation reports an error instead of guessing. Verify which episode it contains, then restore its source URL metadata or move it aside before retrying. Changes to the naming template or destination can prevent an existing file from being reused.

copy avoids re-encoding. Software codec choices include h264, h265, and av1; hardware options include h264_nvenc, hevc_nvenc, h264_amf, hevc_amf, av1_amf, h264_qsv, hevc_qsv, and av1_qsv. These require a compatible FFmpeg build and, for hardware encoding, the corresponding device and drivers.

The codec setting applies to download paths that encode video through FFmpeg. Direct HTTP downloads copy the source media regardless of this preference. Remuxing into MP4 may fall back to H.264/AAC if stream copy fails because the source codecs are incompatible with that container.

Model-specific naming can differ, particularly for manga and movies. MegaKino and Moflix format all template path components, including percent placeholders, and sanitize metadata. Their series paths use padded seasons and three-digit episode numbers; MegaKino treats its flat episode list as season 01. Neither model supplies an IMDb ID, so an empty default IMDb tag is omitted. Movies omit the default season folder and episode marker and respect ANIWORLD_MOVIE_FOLDER. An existing file at the configured template path takes priority over a fallback file at a supported model-specific path with the requested extension. Reused files retain their names. Keep SxxEyy or longer episode markers and matching title folders for Library and Auto-Sync recognition. Root-level movies saved with ANIWORLD_MOVIE_FOLDER=0 are not listed by the Library scanner. Use Settings → path preview or the Python model's path attributes to inspect the result before a large batch.

AniWorld, SerienStream and Hanime currently retain only the first two folder components and the final filename; additional intermediate folders are dropped. MegaKino, Moflix and the HentaiTV family preserve deeper folder layouts. Empty optional metadata is not cleaned consistently across all formatters. Keep template components relative and avoid ..: some formatters do not enforce containment beneath the chosen download root.

Library and Auto-Sync expect title folders directly beneath each download root or language folder. An extra category folder such as Anime/{title}/... is not understood as another title level. The path preview is an AniWorld series example plus a fixed movie example; it does not validate every backend's output.

Sources and playback ​

SettingDefaultPurpose
ANIWORLD_RANDOM_ANIME0Choose a random anime
ANIWORLD_USE_STO_SEARCH0Prefer SerienStream for interactive search
ANIWORLD_ANISKIP0Skip intros and outros when timing data exists
ANIWORLD_KEEP_WATCHING0CLI Watch/Syncplay: continue from an episode URL through the rest of its season
ANIWORLD_ENABLE_HTV0Show Hanime's (hanime.tv) Web UI tab
ANIWORLD_ENABLE_HENTAITV0Show HentaiTV's (hentai.tv) Web UI tab
ANIWORLD_ENABLE_HENTAIHAVEN0Show HentaiHaven's (hentaihaven.xxx) Web UI tab
ANIWORLD_ENABLE_KINOX0Enable Kinox support
ANIWORLD_ENABLE_BURNINGSERIES0Enable BurningSeries support
ANIWORLD_KINOX_DOMAINEmpty, uses kinox.toOverride the Kinox hostname, without https://
ANIWORLD_USE_IINA1Use IINA for ordinary watching on macOS; use 0 for mpv. Syncplay always uses mpv

Site toggles control Web UI visibility. See Supported Sites for every toggle and disabled default. They are not a guarantee that a backend works, and do not remove it from the Python package.

Syncplay ​

SettingDefaultPurpose
ANIWORLD_SYNCPLAY_HOSTEmpty, uses syncplay.pl:8998Server hostname and port
ANIWORLD_SYNCPLAY_ROOMEmptyJoin this room, or generate one from the episode filename
ANIWORLD_SYNCPLAY_USERNAMEEmpty, uses your system usernameDisplay name
ANIWORLD_SYNCPLAY_PASSWORDEmptyHash the episode filename with this value to derive a private room name; ignored when a room is specified

The password changes the generated room name; it is not a Syncplay server authentication password. CLI Syncplay flags override these values for that invocation.

Auto-Sync ​

dotenv
ANIWORLD_ENABLE_AUTOSYNC=1
ANIWORLD_AUTOSYNC_MODE=interval
ANIWORLD_AUTOSYNC_INTERVAL=24h
ANIWORLD_AUTOSYNC_NEW_ONLY=0

For fixed times, use ANIWORLD_AUTOSYNC_MODE=cron and ANIWORLD_AUTOSYNC_CRON="0 3 * * *". See Auto-Sync for how library matching, exclusions, and scheduling work.

Web authentication ​

Local authentication can be enabled with aniworld -w -wA. To create the first administrator without opening the setup page:

dotenv
ANIWORLD_WEB_ADMIN_USER=admin
ANIWORLD_WEB_ADMIN_PASS=change-this-password

Authentication modes can also be set through ANIWORLD_WEB_AUTH, ANIWORLD_WEB_SSO, and ANIWORLD_WEB_FORCE_SSO. For local accounts plus SSO, set both ANIWORLD_WEB_AUTH=1 and ANIWORLD_WEB_SSO=1. SSO alone does not enable authentication; forced SSO enables both.

OIDC single sign-on ​

Install aniworld[sso], then use aniworld -w -wA -wS to offer SSO beside local accounts, or aniworld -w -wFS for SSO only. Register https://aniworld.example.com/oidc/callback as the redirect URI at your identity provider, replacing the origin with your public app URL.

dotenv
ANIWORLD_WEB_BASE_URL=https://aniworld.example.com
ANIWORLD_OIDC_ISSUER_URL=https://login.example.com/realms/main
ANIWORLD_OIDC_CLIENT_ID=aniworld
ANIWORLD_OIDC_CLIENT_SECRET=secret
ANIWORLD_OIDC_DISPLAY_NAME=SSO
ANIWORLD_OIDC_ADMIN_SUBJECT=

ANIWORLD_OIDC_ADMIN_SUBJECT matches the identity provider's subject (sub) to promote an SSO user to administrator. The older ANIWORLD_OIDC_ADMIN_USER matches the display username. Currently either match grants admin access, even when both settings are supplied; leave the username setting empty when using a subject. If no admin exists, the first successful SSO login becomes admin even when a different subject is configured. Restrict access at the identity provider during initial setup.

Set the issuer, client ID, and client secret before enabling SSO-only login. Missing OIDC values can leave an environment-configured SSO-only instance without a working login method; the CLI force flag rejects missing values. A missing SSO dependency aborts startup when SSO is forced.

HTTPS reverse proxy ​

Set ANIWORLD_WEB_BASE_URL to the external origin, for example https://aniworld.example.com, for redirects and secure session cookies. ANIWORLD_WEB_TRUSTED_PROXY accepts the address of the proxy directly connected to Waitress; it trusts one proxy hop for X-Forwarded-For and X-Forwarded-Proto. Without it, forwarded headers are not trusted. This matters for client-IP login throttling as well as HTTPS detection.

Use the actual proxy address and prevent direct public access to the backend. The current setting supports one hop, so account for that when deploying multiple proxies.

Discord bot ​

The Web UI can run a Discord bot beside the server.

SettingPurpose
ANIWORLD_DISCORD_BOT_ENABLEDEnable the bot
ANIWORLD_DISCORD_TOKENDiscord bot token
ANIWORLD_DISCORD_OWNER_IDOwner account ID
ANIWORLD_DISCORD_MODEstandard requires owner approval; advanced queues directly
ANIWORLD_DISCORD_REQUEST_ROLE_IDRole allowed to create requests
ANIWORLD_DISCORD_GUILD_IDGuild used for command registration
ANIWORLD_DISCORD_LANGUAGEBot response language
ANIWORLD_DISCORD_ANNOUNCE_CHANNEL_IDChannel for announcements

The Settings page is the easiest place to configure these values and saves them to .env. See Discord requests for the workflow.

Captcha solving ​

The app opens Chromium and tries checkbox challenges, including Turnstile, hCaptcha and reCAPTCHA, plus ALTCHA verification. Image challenges need your input: use the browser window in CLI mode or click the browser screenshot on the Web UI queue page. The defaults require no extra configuration; successful verification still depends on the site and its challenge.

SettingDefaultPurpose
ANIWORLD_CAPTCHA_VISIBLEautoauto shows CLI solving windows and keeps Web UI and background helper windows off-screen. 1 always shows the window; 0 always keeps it off-screen. Chromium remains headed in every mode.
ANIWORLD_CAPTCHA_TIMEOUTEmptyPositive seconds to wait for a solve. Empty, invalid or nonpositive values keep the flow's default: 300 seconds for CAPTCHA/Hanime, 90 for S.to and 30 for Moflix.
ANIWORLD_CAPTCHA_MANUAL01 leaves checkbox clicks and ALTCHA verification to you. Completed forms still submit automatically. Use ANIWORLD_CAPTCHA_VISIBLE=1 if you need to interact with a background helper window.
ANIWORLD_CAPTCHA_DEBUG_LOG01 logs browser console warnings/errors, page errors and failed requests to the app log.

Set these values in the app's .env, or in the Docker service's environment, and restart the app or recreate the container after changing them.

For example, to solve widgets yourself in a visible window and allow ten minutes:

dotenv
ANIWORLD_CAPTCHA_VISIBLE=1
ANIWORLD_CAPTCHA_MANUAL=1
ANIWORLD_CAPTCHA_TIMEOUT=600

For Web UI or Docker use, leave ANIWORLD_CAPTCHA_VISIBLE=auto and interact through the queue's CAPTCHA viewer. A visible window opens on the machine running AniWorld; it does not open on a remote Web UI user's desktop.

AniWorld Downloader is open source.