Tdarr: Distributed Transcode Automation for Media Libraries

The problem Tdarr is built around: a library that has drifted

A media library that grows for years stops being uniform. The README gives the concrete example: some files carry 15 or more audio, commentary and subtitle tracks in several languages, and those extra streams can add more than a gigabyte per file. Codecs drift too, since older rips are often h264 while newer hardware handles h265 (hevc) better. The README states that a common use is converting h264 to h265 and saving 40% to 50% in size.

Tdarr is for the person who has already accepted that this cleanup is a batch job, not a manual one. The README describes the target user indirectly: someone running Sonarr or Radarr alongside it, someone with spare hardware, someone willing to write or at least read JavaScript plugins. The project's own framing is that it is modular and configurable, and that configurability is the whole point. If you only want to shrink a folder of files once, the machinery here is heavier than the task.

How the server, the nodes and the plugin stack fit together

Tdarr is not one process. The README describes two components. Tdarr_Server is the central process that all nodes connect with. Tdarr_Node is a process that runs on the same device or another one and collects tasks from the server. Nodes are available for Windows, Linux (including Linux arm and arm64) and macOS, and the README notes that spare hardware can be put to use this way.

The unit of work is the library. Each library you add has its own transcode settings, filters and schedule, so a 4K library and an archive of old TV rips do not have to share rules. Workers are split into four types: Transcode CPU, Transcode GPU, Health Check CPU and Health Check GPU. The README states that worker limits can be managed by a scheduler or manually, and that workers can be started and stopped as needed.

What actually decides whether a file is touched is the plugin stack. The README's example stack is short and worth reading as a design statement: transcode non-hevc files into hevc, remove subtitles, remove metadata if there is a title, add aac stereo audio if none exists with English preferred, remove closed captions. Each plugin is conditional, so it only acts when the condition matches. Community plugins cover most of that list; the fourth one in the example can be created in the plugin creator interface and then appears as a local plugin. Plugins live in Tdarr/Documents and are written in JavaScript, which means the ceiling on what Tdarr can do is roughly the ceiling on what you can write. The README points to the Tdarr_Plugins repository for the steps.

One detail in the README is easy to skim past and matters in practice: subtitles and closed captions are not the same thing. In the example file the README uses, the closed caption data is embedded inside the h264 video stream rather than sitting in its own subtitle stream. A plugin that removes subtitle streams will not touch it. The README's own recommendation is to handle subtitles with something like Bazarr instead.

Installing Tdarr and running a first transcode rule

The README does not carry installation steps itself. It links to a Download/Setup/Installation page at docs.tdarr.io/docs/installation/windows-linux-macos and to a downloads page at home.tdarr.io/download, and it mentions a hardware transcoding container for Nvidia on unRAID and Ubuntu. Because the repository ships a docker directory and a flatpak directory at the top level, both container and Flatpak paths exist, but the README does not spell out the commands. Treat the docs site as the source of truth for flags and image names.

The shape of a container setup is still visible from the two-component design. You start a server, then start one or more nodes that point at it. The README does not give the exact port, so check the docs rather than guessing; the related searches around "tdarr port" suggest this is a common point of confusion. The README's badge links to ghcr.io/haveagitgat/tdarr, and the docs page at docs.tdarr.io/docs/releases/changing-version lists the available images. Volume paths and the node's server address have to come from that page.

Once the server is up, the first useful action is not a transcode. It is a health check. The README lists Health Check CPU and Health Check GPU as worker types, and video health checking is named in the first line of the README. Running a health check pass over a library before converting anything tells you which files are already damaged, and a transcode of a damaged file is wasted GPU time. After that, the smallest real rule is the one the README gives as the common case: a plugin that transcodes non-hevc files into hevc. Add it to a library's stack, let the scheduler or a manual start run a worker, and watch the job reports the README shows as a feature.

Where Tdarr is the wrong tool

Tdarr assumes you have a library worth automating. The README states the project has been tested on a 1,000,000 file dummy library, which tells you the intended scale. For a few dozen files, the time spent wiring a server, a node and a plugin stack exceeds the time spent converting them by hand.

The second limitation is that the plugin stack is code. The README is explicit that plugins are JavaScript and that creating new ones needs a bit of coding experience, or at least the patience to read existing ones. If none of the community plugins does what you want and you cannot write the missing one, Tdarr stops being useful at exactly the point you need it. That is a different failure mode from a tool with a fixed feature set: there is no menu to fall back on.

The third is the closed caption case described above. Removing subtitle streams is a plugin. Removing closed captions embedded in a video stream is a different operation, and the README treats them as separate problems. Anyone who assumes "remove subtitles" covers both will find captions surviving the pass.

Finally, GPU workers are not free of setup. The README mentions a hardware transcoding container and Nvidia runtime configuration, which means the GPU path carries host-level configuration that the CPU path does not. If your host does not already expose the GPU to containers, budget time for that before the first transcode.

Tdarr compared with Unmanic and HBBatchBeast

The README itself names HBBatchBeast as the desktop application with similar functionality, and describes it as the alternative for people who do not want the server and node split. That is the clearest difference in approach: HBBatchBeast runs on one machine, while Tdarr separates the scheduler from the workers so several machines can pull from the same queue. If you have one machine, the split buys you nothing except configuration surface.

Unmanic is the other comparison people search for. The README does not describe Unmanic's internals, so the honest statement is narrower: Tdarr's distinguishing design choice is the plugin stack. Processing decisions are expressed as an ordered list of conditional JavaScript plugins rather than as a fixed set of built-in options, and the README's example stack of five steps is the canonical illustration. A tool with a fixed option set will be faster to configure and slower to extend. Which of those you want depends on whether your requirements are already covered by someone else's plugin.

Maintenance, licensing and what upgrading costs

The repository is not archived and the last push was on 2026-09-19, so the codebase is being touched. That is separate from the release list, which is worth reading carefully: the most recent release shown is v1.2066-Beta from 2020-09-18, and the two before it are from May and April 2020. The README meanwhile describes Tdarr V2 and package.json carries version 2.62.01. The release feed and the package version do not agree, so do not use the releases list to decide which version to install. The README points to docs.tdarr.io/docs/releases/changing-version for the available images.

Upgrade cost is mostly plugin compatibility. Because plugins are JavaScript files stored in Tdarr/Documents and community plugins come from a separate repository, a version change can affect the plugins you depend on, not just the server. The README does not document rollback, so there is no stated procedure for returning to a previous version if a plugin breaks after an upgrade. Plan for that gap rather than assuming one exists.

On licensing, package.json says the license is "See LICENSE.md" and the repository's declared licence is NOASSERTION, which means the repository metadata does not resolve to a standard SPDX identifier. Read LICENSE.md directly before deciding how you can use or redistribute the code. Nothing here is legal advice, and the licence file is the only thing that settles it.

Editorial conclusion

Adopt Tdarr if you already run Sonarr, Radarr or a similar library manager and you have spare hardware to give it, because the server and node split only pays off when more than one machine is doing the work. Do not adopt it if you want a one-click converter: there is no single binary that reads a folder and writes smaller files, and the plugin stack has to be configured before anything useful happens. Before installing, check the download page at home.tdarr.io for the current images and read docs.tdarr.io on the difference between Tdarr_Server and Tdarr_Node, because the README assumes you already know which one you are starting.

Frequently asked questions

Official sources

1. HaveAGitGat/Tdarr on GitHub
2. Issues
3. README
4. Releases