# Install tvnamer with Homebrew, Nix, apt Automatic TV episode file renamer that uses data from thetvdb.com. Version 3.0.4 via Homebrew; verified 2026-05-15. Also installable with nix: nix profile install nixpkgs#tvnamer. ## Install ```sh sudo av install brew:tvnamer ``` Additional install commands: ### macOS - Homebrew (100%): ```sh brew install tvnamer ``` Evidence: local Homebrew formula metadata ### Linux - Nix (92%): ```sh nix profile install nixpkgs#tvnamer ``` Evidence: nixpkgs package indexes: pkgs/by-name/tv/tvnamer/package.nix from https://api.github.com/repos/NixOS/nixpkgs/git/trees/master?recursive=1 - Ubuntu apt (92%): ```sh sudo apt install tvnamer ``` Evidence: Ubuntu 24.04 LTS package indexes: tvnamer from https://archive.ubuntu.com/ubuntu/dists/noble/universe/binary-amd64/Packages.gz ## Package facts - **Package key:** brew:tvnamer - **Package manager:** Homebrew - **Package manager page:** - **Version:** 3.0.4 - **Source summary:** Automatic TV episode file renamer that uses data from thetvdb.com - **Homepage:** - **Repository:** - **License:** Unlicense - **Source archive:** - **Last updated:** 2026-05-15T11:15:11Z - **Generated:** 2026-08-04T22:13:35+00:00 ## Executables - tvnamer (cli) - tvnamer (alias) ## Dependencies - certifi - python@3.14 ## Install behavior - Post-install hook: not defined - Bottle: available on all ## Freshness - Page generated: 2026-08-04 - Package-manager version: 3.0.4 - Package-manager updated: 2026-05-15 - Local data: ok - Upstream repository: https://github.com/dbr/tvnamer - info: No cached GitHub release or tag data was available. ## Project history and usage tvnamer is a Python command-line utility for renaming TV episode files by parsing filenames and looking up episode metadata through tvdb_api and TheTVDB data. ### Project history The official GitHub repository was created in July 2009, placing tvnamer in the older generation of home-media-library command-line tools. Its README describes the core transformation from scene-style names such as `some.show.s01e03...avi` to cleaner names such as `Some Show - [01x03] - The Episode Name.avi`. The README documents a v2-era shift toward extensive JSON configuration, saying custom configuration was one of the largest improvements in tvnamer v2. It later records Python 3.5+ support and notes that tvnamer 3 was the last version to support Python 2.7. ### Adoption history tvnamer's adoption came from media-library automation rather than from a single platform ecosystem. The official README says pip is the official install method and also lists community packaging for Homebrew, Debian, FreeBSD/DragonFlyBSD/MacPorts, and Nix; the supplied package metadata records Homebrew, Nix, and Ubuntu entries. Its package-manager relevance comes from the old but durable need to normalize downloaded or ripped TV episode files before media centers, NAS folders, and archive scripts consume them. ### How it is used The basic workflow is `tvnamer file_or_directory`: tvnamer parses episode-like filenames, searches TVDB data, prompts the user to confirm a match, and renames files. It can run on individual files, multiple paths, directories, or recursively with `--recursive`. For automation, the README highlights `--selectfirst`, `--always`, and `--batch`, plus `--series-id` for disambiguation. Users can save or place a JSON config at `~/.config/tvnamer/tvnamer.json` to customize language, filename formats, replacements, and safety behavior. ### Why package nerds care tvnamer is a classic package-nerd utility: small, scriptable, long-lived, and very specific. It sits at the intersection of Python packaging, Homebrew/Debian/Nix distribution, and personal media curation workflows. ### Timeline - 2009: Official GitHub repository created. - 2010s: v2 series introduced JSON configuration according to the README. - 2020: README notes tvnamer 3 as the final Python 2.7-compatible release. - 2021: GitHub metadata shows the last push in May 2021 while package metadata still records active package-manager entries. ### Related projects - TheTVDB - tvdb_api - Python packaging - media-center file organization ### Sources - GitHub API for dbr/tvnamer: repository created 2009-07-16, homepage, description, license, and push metadata. - current_curation.repo: existing curated repository URL corroborates official GitHub repo. - - source_facts.package-manager: Homebrew, Nix, and Ubuntu package-manager presence. ## Security Notes No matching local secret-handling manifest was found for tvnamer. Package metadata is still published here so future coverage has a stable package URL. ## Configuration and credential file locations These source-backed paths show where this package keeps local settings or durable credentials. Automic Vault can use them as review targets for secret scanning, migration, and command approval. ## Configuration files - Unix: ~/.config/tvnamer/tvnamer.json ## Source Database Details - **Source Database:** Homebrew formula API - **Tap:** homebrew/core - **Full Name:** tvnamer - **Version Scheme:** 0 - **Revision:** 14 - **Head Version:** HEAD - **Bottle Stable Root URL:** - **Deprecated:** no - **Disabled:** no - **Keg Only:** no - **URL Keys:** head, stable ## Other Package-Manager Records - Nix - tvnamer: normalized package name match | nixpkgs package indexes: pkgs/by-name/tv/tvnamer/package.nix from https://api.github.com/repos/NixOS/nixpkgs/git/trees/master?recursive=1 - Ubuntu apt - tvnamer - 3.0.4-2: normalized package name match | Ubuntu 24.04 LTS package indexes: tvnamer from https://archive.ubuntu.com/ubuntu/dists/noble/universe/binary-amd64/Packages.gz | utility to rename TV-show episodes files | https://github.com/dbr/tvnamer ## Related links - [Source-control packages](https://pkg.so/source-control-tools/) - Belongs to a source-control command family. - [Terminal utility packages](https://pkg.so/terminal-utilities/) - Matched terminal and command-line workflow metadata. - [Language runtime packages](https://pkg.so/language-runtime-packages/) - Matched language runtime, compiler, or interpreter metadata. - [Networking and protocol packages](https://pkg.so/networking-protocol-tools/) - Matched network, protocol, or remote-service metadata. - [python@3.14](https://pkg.so/brew/python-3-14/) - Runtime dependency declared by Homebrew. - [pdfly](https://pkg.so/brew/pdfly/) - Shares pkgdb curated category or tags: cli, media, metadata, python. - [instaloader](https://pkg.so/brew/instaloader/) - Shares pkgdb curated category or tags: cli, media, metadata, python. - [flac](https://pkg.so/brew/flac/) - Shares pkgdb curated category or tags: cli, media, metadata. - [exiftool](https://pkg.so/brew/exiftool/) - Shares pkgdb curated category or tags: cli, media, metadata. - [ocrmypdf](https://pkg.so/brew/ocrmypdf/) - Shares pkgdb curated category or tags: cli, media, python. - [taglib](https://pkg.so/brew/taglib/) - Shares pkgdb curated category or tags: cli, media, metadata. - [vapoursynth](https://pkg.so/brew/vapoursynth/) - Shares pkgdb curated category or tags: cli, media, python. - [gallery-dl](https://pkg.so/brew/gallery-dl/) - Shares pkgdb curated category or tags: cli, media, python. - [sacad](https://pkg.so/brew/sacad/) - Both packages touch the same language runtime or ecosystem. Shared terms: automatic, cli, media, metadata, python. - [tubeup](https://pkg.so/brew/tubeup/) - Both packages touch the same language runtime or ecosystem. Shared terms: certifi, cli, media, metadata, python. - [animdl](https://pkg.so/brew/animdl/) - Both packages touch the same language runtime or ecosystem. Shared terms: certifi, cli, media, python, python-3-14. ## Combined YAML source View the package source record on GitHub. [combined/tvnamer.yml](https://github.com/mxcl/pkgdb/blob/main/combined/tvnamer.yml) ## Sources - pkg.so package database - Geiger risk classifier - package-page enrichment - curated configuration and credential file locations - curated package history - package version freshness - pkgdb category and tag curation - package relationship graph - external package-manager database matches - cross-ecosystem install command graph