Dispatcharr: self-hosted IPTV stream management with HDHomeRun emulation

What Dispatcharr solves for people juggling several IPTV providers

Dispatcharr is not an IPTV provider. It is a management layer that sits between the providers you already pay for and the media server you already run. The README frames it as "the *arr family's IPTV cousin", and that comparison is the clearest way to place it: Sonarr and Radarr organize libraries you already own, Dispatcharr organizes streams you already subscribe to.

The problem it targets is the mess that builds up once you have more than one source. Two providers mean two M3U URLs, two EPG feeds, overlapping channel numbers, and duplicate entries for the same network. Plex, Emby and Jellyfin each want a tuner, and none of them is good at merging sources or rewriting channel lineups. Dispatcharr imports M3U and Xtream Codes playlists, filters and organizes channels, matches XMLTV or Schedules Direct guide data to them, and exports the result in several formats.

The intended user is a self-hoster with a media server and at least one paid or free IPTV source. The project is explicitly self-hosted with no third-party dependencies in the hosting path, which matters if your providers are geo-restricted and you route everything through a VPN container. If you have no upstream provider, Dispatcharr has nothing to dispatch.

How the proxy, EPG matching and HDHomeRun emulation fit together

The architecture visible in the repository is a Django application (Django 6.0.8, Python 3.13 or newer) with Celery and Redis for background work, Daphne and Channels for WebSocket traffic, and a JavaScript frontend under frontend/. The top-level layout splits into apps/, core/, dispatcharr/, docker/, docs/ and scripts/, which matches the usual Django project shape: apps/ holds the domain modules, core/ the shared plumbing, dispatcharr/ the project settings.

The runtime path for a stream is a chain rather than a single step. A client requests a channel from Dispatcharr. Dispatcharr resolves it through a stream profile, which is the configuration for how it connects to the backend stream. The README lists VLC, FFmpeg, Streamlink and custom commands as stream profile options, and the dependency list confirms all three libraries are present (python-vlc, streamlink, yt-dlp). An output profile then optionally transcodes what the stream profile delivers before it reaches the client, with fMP4 or MPEG-TS container selection and use cases such as AC3 for media servers or AAC for browsers.

EPG matching is the part that decides whether the result is usable. Dispatcharr accepts XMLTV, Schedules Direct or generated dummy guides, and the README says it can auto-match EPG to channels or generate custom schedules. The rapidfuzz and sentence-transformers dependencies suggest the matching is not purely exact-string; sentence-transformers in particular implies embedding-based similarity for channel-name alignment. That is a reasonable design for the problem, since provider channel names rarely match guide names byte for byte, but it also means the matching is probabilistic and will need review on ambiguous names.

The HDHomeRun emulation is what makes the media server integration work. Plex, Emby and Jellyfin all know how to discover an HDHomeRun device on the network. Dispatcharr presents itself as one, so those servers treat it as a live TV source and can record into their own DVR libraries. Dispatcharr also exports M3U, XMLTV EPG and the Xtream Codes API, so you are not locked into the HDHomeRun path.

Installing Dispatcharr with Docker and reaching the setup page

The README recommends Docker and gives a single-container quick start. This pulls the image from GitHub Container Registry and runs it with port 9191 mapped and a named volume at /data.

docker pull ghcr.io/dispatcharr/dispatcharr:latest
docker run -d \
  -p 9191:9191 \
  --name dispatcharr \
  -v dispatcharr_data:/data \
  ghcr.io/dispatcharr/dispatcharr:latest

After that the web UI is on port 9191. The first-time setup page is limited to local and private networks by default. If you are installing on a VPS or reaching the UI from a public IP, the README gives two options: create the admin from the shell, or allow your client IP explicitly.

docker exec <container> python manage.py createsuperuser

The alternative is to set DISPATCHARR_SETUP_ALLOWED_IP to your client IP before starting the container. The setup page itself displays the IP that Dispatcharr sees, which is the value to compare against if you are unsure whether your request is arriving from the address you expect.

If a reverse proxy sits in front of Dispatcharr, set DISPATCHARR_TRUSTED_PROXIES to the proxy's IP or CIDR. The README states that the default trusts private and loopback peers, and that the value none makes Dispatcharr ignore forwarded headers. This setting affects Network Access rules, the Stats page and rate limiting, so a wrong value means those features operate on the proxy's address rather than the real client's.

For anything beyond a trial, the README points at the Docker Compose files in docker/, including an all-in-one deployment it marks as recommended. The README does not document a rollback path for a failed upgrade, so back up the /data volume before pulling a new image.

Where Dispatcharr is the wrong tool

The first limitation is upstream dependency. Dispatcharr proxies streams; it does not supply them. If a provider's M3U or Xtream endpoint is down, Dispatcharr can fail over to a backup source, but it cannot invent one. Automatic failover only helps if you have configured more than one source for the same channel, and the README does not describe how failover ordering is decided.

The second is operational weight. The dependency list includes torch==2.14.0+cpu and sentence-transformers==6.0.1, which are large. The pyproject.toml pins torch to the CPU-only PyTorch index, so there is no GPU acceleration path in the default install. Transcoding with FFmpeg output profiles adds CPU load on top of that. A small VPS that comfortably runs a playlist proxy may not comfortably run Dispatcharr with several simultaneous transcoded sessions.

The third is that transcoding is optional but not free in configuration terms. Stream profiles and output profiles are separate concepts, and the README describes them in one line each. Getting the combination right for a mixed client population (a media server that wants AC3, a browser that wants AAC) requires understanding both layers.

Finally, Dispatcharr is not a media server. It does not replace Jellyfin, Plex or Emby, and it does not manage a local film library. The VOD feature streams movies and series from your providers with metadata and IMDB/TMDB integration. It is not a library manager for files you own.

Dispatcharr compared with Threadfin and ErsatzTV

Threadfin is the closest comparison, and it is a direct one because both projects occupy the same slot: an IPTV proxy that presents an HDHomeRun tuner to Plex, Emby or Jellyfin. Threadfin is a Go application derived from xTeVe, and its scope is the proxy and the tuner emulation. Dispatcharr's README describes a broader surface: built-in DVR with series rules, optional Comskip commercial stripping, in-progress playback, Xtream catch-up and timeshift, VOD with metadata, multi-user accounts with granular permissions, and a plugin system. The difference is therefore scope rather than protocol. If you only need to merge playlists and hand a tuner to Plex, Threadfin is the smaller tool. If you want recording, catch-up and per-user access control in the same application, Dispatcharr is the one that ships those features.

ErsatzTV is a different kind of tool. It generates scheduled channels from your own media library, so the input is local files rather than provider streams. Dispatcharr and ErsatzTV are complementary more than competing: one organizes what you subscribe to, the other builds channels from what you own. Choosing between them is really a question of whether your content comes from a provider or a disk.

Jellyfin is not an alternative at all. It is a media server, and Dispatcharr is designed to feed it through HDHomeRun emulation. The README's integration examples name Plex, Emby and Jellyfin as targets, not substitutes.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-22, one day before the date used for this assessment. Release cadence is visible in the tags: v0.29.0 on 2026-08-09, v0.30.0 on 2026-08-29, v0.31.0 on 2026-09-13. That is roughly a release every two to three weeks, which means upgrade frequency is a real operational cost rather than a theoretical one. Nothing in the README describes a migration process, a database schema version check or a downgrade path, so the practical upgrade procedure is to back up the /data volume, pull the new image and restart.

The licence is AGPL-3.0, declared in pyproject.toml as AGPL-3.0-only and listed in the repository as AGPL-3.0. The practical consequence for most self-hosters is nil, since running the software for yourself is not distribution. It matters if you modify Dispatcharr and expose it to users over a network: the AGPL's network clause is the reason some companies avoid it. This is a description of the licence's terms, not legal advice, and anyone embedding Dispatcharr in a product should read the licence text in LICENSE rather than rely on this paragraph.

The Python version floor is 3.13. That is a recent interpreter, so a host running an older distribution Python will need a container or a newer interpreter. The Docker image sidesteps this, which is another argument for the documented Docker path over a source install.

Editorial conclusion

Adopt Dispatcharr if you already pay for one or more IPTV or Xtream providers and want a single proxy layer that filters channels, merges EPG and hands Plex, Emby or Jellyfin an HDHomeRun tuner instead of a raw playlist per provider. Skip it if you have no upstream provider, if you want a hosted service, or if you cannot run Docker and a Python 3.13 stack. Before committing, verify three things: that your provider's M3U and Xtream endpoints import cleanly, that the setup page is reachable from your network or that DISPATCHARR_SETUP_ALLOWED_IP is set correctly, and that DISPATCHARR_TRUSTED_PROXIES matches your reverse proxy so Stats and Network Access see real client IPs.

Frequently asked questions

Official sources

1. Dispatcharr/Dispatcharr on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases