Skip to main content

anipyrenamer

version: 2.6.0

anipyrenamer is a command-line tool that renames anime files using ED2K hash lookups from AniDB, with local SQLite caching for faster reruns and offline support.

It fits alongside local media libraries (Plex/Jellyfin folders, plain disk collections): you point it at files or folders, it resolves titles and episode metadata from AniDB, then renames in place or into a destination tree.

Requirements

  • Python 3.13+
  • An AniDB account and UDP API client registration (for online lookup). You can use --offline when the SQLite cache already has the rows you need.

Install

# From the repository root (the directory that contains pyproject.toml).

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

pip install -e ".[dev]"
cp .env.example .env
# edit .env — never commit secrets

For a minimal install without dev dependencies: pip install -e .

Optional helper scripts are in scripts/ (install.sh / install.bat, install-dev.*, setup-venv.*).

Configuration

Put credentials and client strings in .env (see .env.example). Required for online mode:

  • ANIDB_USERNAME, ANIDB_PASSWORD, ANIDB_UDP_CLIENT, ANIDB_UDP_CLIENTVER, ANIDB_LOCAL_PORT

Optional:

  • ANIDB_API_KEY (when UDP encryption is enabled)

Where .env is loaded: project/package directory and parents first, then a well-known config path: Windows %APPDATA%\anipyrenamer\.env, Linux/macOS ~/.config/anipyrenamer/.env.

Cache: When a parent directory contains pyproject.toml, the default database is project root .cache/anipyrenamer_cache.sqlite. Otherwise it lives under the same config directory as .env. Override with --db.

Usage

anipyrenamer <path> [paths...]

Examples:

anipyrenamer "C:\Videos\Anime" --dry-run
anipyrenamer "C:\Videos\Anime"
anipyrenamer "C:\Videos\Anime" --yes
anipyrenamer "C:\Videos\Anime" -t "%title% S01E%epno%%ext%" -d "C:\Renamed"
anipyrenamer "C:\Videos\Anime" --mylist

Use anipyrenamer --help for all options.

Confirmation prompts

The rename-apply confirmation uses Prompt text (Y/n/a): — Y (default), n, or a (yes to all remaining).

The --mylist wizard uses Prompt text (Y/n): — Y (default) or n, with no "yes to all": every MyList prompt is an independent yes/no, and the final Apply MyList updates? prompt is the only confirmation that writes to your AniDB MyList.

MyList storage states

When you run --mylist and choose to set storage, the menu is 0-indexed and the number you type is the AniDB MyList state code that gets saved:

Key Meaning
0 Unknown/None
1 Internal (on hdd)
2 External (on cd/dvd)
3 Deleted
4 Remote (NAS/cloud)
5 Exit (abort without writing)

Only the state code is written; no free-text storage name is sent. Verified on 2026.06.26 against the live AniDB MyList UI. Legacy AniDB clients that label 4 as "shared" or 5 as "release" are out of date — AniDB repurposed those codes after retiring P2P sharing.

Platforms

Developed and tested on Windows and Unix-like systems (Linux, macOS). Paths in examples use Windows style where helpful; adjust for your OS.

Troubleshooting

See docs/runbook.md for exit codes, common failures, and safe reruns.

Notes for other AniDB UDP API developers

anipyrenamer speaks AniDB's UDP API, which enforces strict flood protection. If you're writing your own client, here is the documented policy from AniDB's UDP API Definition (the authoritative source), and how we chose to honor it:

  • Two documented rate limits. The short-term limit of one packet per 2 seconds begins after the first five packets; over an extended run, the long-term guidance is one packet per 4 seconds. Exceeding these doesn't fail loudly — AniDB drops the excess packets until your rate is acceptable again. For bulk work (e.g. syncing a season to MyList), pace to the long-term rate, or you can trigger flood protection and dropped packets. (As a conservative choice of our own — not an AniDB requirement — anipyrenamer spaces even its first five packets by 2 seconds, then 4 seconds sustained.)
  • 555 BANNED is the explicit signal. After flood protection triggers, AniDB may simply stop replying, so don't depend on receiving a 555. When one does arrive (sometimes carrying a reason such as Flooding), treat it as the point to latch a "banned" state and stop sending. (For MyList operations, anipyrenamer treats a 555 reply as the point to latch a banned state and stop sending — including LOGOUT.)
  • Don't over-interpret silence. A timeout without a 555 is ambiguous — it may be a network problem or rate-limiting. Use bounded backoff and surface it as an ambiguous network/rate-limit failure; don't treat it as certainly a ban.
  • Cache and reuse metadata. AniDB asks clients not to repeatedly request the same datasets and warns that future enforcement may restrict repeated requests.

For MyList operations, this shaped anipyrenamer's throttle (a minimum gap between every packet) and its ban handling: on a MyList 555, stop the MyList run cleanly and surface the reason; on an unexplained timeout, bounded retries then a clear failure — never retrying a known ban.

Contributing and issues

Report bugs and request features via the project issue tracker on GitHub.

Development

Parts of this codebase were written or refactored with AI-assisted coding tools, alongside manual design, testing, and review. Human maintainers remain responsible for behavior and releases.

License

Distributed under the MIT License. Dependency licenses vary; review them when preparing redistributions (wheel, bundle, installer).

Metadata

Release files for anipyrenamer 2.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for anipyrenamer 2.6.0
File Size Uploaded Provenance Actions
anipyrenamer-2.6.0.tar.gz 101.3 kB With provenance Details for anipyrenamer-2.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for anipyrenamer 2.6.0
File Interpreter ABI Platform Actions
anipyrenamer-2.6.0-py3-none-any.whl Python 3 none any Details for anipyrenamer-2.6.0-py3-none-any.whl

Total release size: 158.7 kB

Release files / anipyrenamer-2.6.0.tar.gz

Download URL anipyrenamer-2.6.0.tar.gz
Size 101.3 kB
Tags Source
SHA-256 checksum
How to use checksums
1e5a939f0b2024084762a5000cea957c521de0ee6fc1f0d09057d96d29d408ce
BLAKE2b-256 checksum
How to use checksums
08eaed3999531a60e036a0b64840506d5c5be26b658656753d75aff53cd08202
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 26, 2026.

Transparency log

Release files / anipyrenamer-2.6.0-py3-none-any.whl

Download URL anipyrenamer-2.6.0-py3-none-any.whl
Size 57.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
09dfd0c9dffbe15303627531d97c44e5da74362a4e1d5745ae3ff9e9a90e78d2
BLAKE2b-256 checksum
How to use checksums
7ccb0adc87fad5c39a77d6e23c21fc5abfda1e738955331ba00fdebeb4212f40
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 26, 2026.

Transparency log

Security for anipyrenamer 2.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for anipyrenamer-2.6.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 26, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page