Add IPTV to Plex: Threadfin in Docker, Step by Step

Short answer: run Threadfin in Docker, give it your M3U and XMLTV links, then add it in Plex under Settings → Live TV & DVR → Set Up Plex DVR by typing its address by hand. The step that stalls most people isn't Plex at all: Docker's default network hides Threadfin from Plex's tuner search, so the wizard says it found nothing. Typing your-server-ip:34400 fixes that.

Before you start

You'll need four things in hand. Getting them sorted first is quicker than discovering a gap halfway through Plex's wizard.

The connection limit matters because Threadfin's "tuner count" should match it. Set four tuners on a two-connection plan and Plex will happily try to record three things at once, and the third will fail. Our piece on IPTV multiple connections explains how providers count them.

If you only have a server, username and password rather than a link, that's an Xtream-style login. You can still use Threadfin, but convert it first using the method in our Plex and Xtream guide.

A quick test saves time: open the M3U URL in VLC on any computer and play two or three channels. If they don't play there, nothing below will make them play in Plex. Our VLC M3U guide covers how.

Step 1: Start Threadfin with Docker Compose

Make a folder, say ~/threadfin, and save this as docker-compose.yml. It follows the project's own example.

services:
  threadfin:
    image: fyb3roptik/threadfin
    container_name: threadfin
    ports:
      - 34400:34400
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    volumes:
      - ./data/conf:/home/threadfin/conf
      - ./data/temp:/tmp/threadfin:rw
    restart: unless-stopped

Three edits before you run it:

• PUID and PGID: run id on Linux and use your own numbers, so the config files belong to you. On Synology, use the IDs of the account that owns the Docker share.
• TZ: set your real time zone. A wrong zone shifts the whole guide by hours, and you'll chase a "broken EPG" that's actually a clock problem.
• Volumes: keep conf on persistent storage. That folder holds your mapping work; lose it and you redo the slowest part.

Then, from that folder, run docker compose up -d and open http://SERVER-IP:34400/web in a browser. You should land on Threadfin's first-run wizard.

Host networking, or not? Plex finds real HDHomeRuns by broadcasting on the local network. In Docker's default bridge mode that broadcast doesn't reach the container, so Plex won't list Threadfin automatically. You can switch to network_mode: host (and drop the ports lines) on Linux, but the simpler habit is to leave bridge mode alone and type the address into Plex in Step 4. Docker Desktop on Windows and Mac doesn't support host mode in the same way anyway.

Step 2: Run the Threadfin wizard

The wizard asks a handful of questions. The answers that work for Plex:

1. Number of tuners: your plan's simultaneous connections, not more.
2. EPG source: choose XEPG. The other option ("PMS") leaves guide matching to Plex's own lineups, which won't recognise most IPTV channels.
3. M3U playlist: paste the playlist URL. Large playlists take a minute or two to parse.
4. XMLTV: paste the guide URL. Threadfin downloads and indexes it.

Afterwards, open Settings and look at the buffer option. Setting it to FFmpeg lets Threadfin pull the stream and hand Plex a clean MPEG-TS feed, which smooths over HLS streams and odd URLs. The Threadfin docs themselves say FFmpeg or VLC "will always be a better solution" than the old built-in buffer. If FFmpeg isn't detected, check the binary path shown on the same page.

Step 3: Filter and map channels

This is the slow part, and it's where a good setup differs from a frustrating one.

Filter first. Under Filter, add rules by group title (for example only the "News" and "Local" groups) or by keyword. Plex struggles with very large lineups; users commonly report problems above roughly 480 channels per tuner, so aim well below that. Fewer channels also means a faster guide.

Then map. In Mapping, each channel shows a red or green status. Red means it has no guide data attached. For each channel you want:

• Pick the matching XMLTV channel from the dropdown. If the playlist's tvg-id matches the guide, Threadfin often does this for you.
• Set the channel number you want Plex to show. Clean numbers (101, 102, 103) beat whatever the playlist shipped with.
• Deactivate anything you won't watch, even if it's in your filtered groups.

Only active, mapped channels appear in Threadfin's output, so this step decides exactly what Plex will see. The details of IDs and numbering are covered in our clean-M3U guide for Plex.

Step 4: Add the tuner in Plex

Use Plex Web (app.plex.tv or the server's own address) signed in as the server owner.

1. Go to Settings, pick your server, then under Manage choose Live TV & DVR.
2. Click Set Up Plex DVR. Plex searches for tuners.
3. When it finds nothing, choose the option to enter the device's network address manually and type SERVER-IP:34400. Plex should now show a "Threadfin" HDHomeRun-style device with your tuner count.
4. Continue to channel scanning. Plex reads the lineup Threadfin reports.
5. At the guide step, choose the XMLTV option instead of a postcode. Enter http://SERVER-IP:34400/xmltv/threadfin.xml and give the guide a name.
6. Review the channel mapping. Because Threadfin already matched IDs, most rows should be filled. Untick any you don't want.
7. Click Continue. Plex downloads the guide; the first load can take a few minutes.

A Plex moderator confirmed on the forum that adding a tuner and watching doesn't need Plex Pass, though a 2024 Plex Web bug briefly showed only a "Get Plex Pass" button to free users; opening the server directly at its local address got round it. Recording does need Plex Pass ($6.99 a month, $69.99 a year or $249.99 lifetime since April 2025).

Step 5: Check it end to end

Don't trust the wizard's green ticks. Test what you'll actually use:

• Open Live TV in Plex Web and play three channels from different groups.
• Play the same channels on the device you'll use most, especially if it's a Fire TV or Android TV, whose Plex apps are the fussiest about stream formats.
• Open the guide two hours ahead and check that programme times look right for your time zone.
• With Plex Pass, record a 10-minute slot and play it back from the library.
• Start as many streams as your tuner count, then one more. The extra one should fail cleanly with a "no tuners available" message rather than kicking another viewer off.

When a step fails

For buffering that isn't tied to Plex, our buffering guide walks through finding the bottleneck.

Keeping it running

Set Threadfin to refresh the playlist and XMLTV daily (Settings, under update schedule). Pull a new image now and then with docker compose pull && docker compose up -d; your mapping survives because it lives in the conf volume. If your provider renumbers channels, re-check Threadfin's mapping first, then hit Refresh Guide in Plex's Live TV & DVR settings.

One last point. Everything here works with any playlist, which is exactly why it matters which playlist you feed it. Use a source you're licensed to watch; our guide to checking an IPTV provider explains what to look for.

Quick answers

What port does Threadfin use for Plex?

Threadfin listens on port 34400 by default. The web interface is at /web, the playlist at /m3u/threadfin.m3u and the guide at /xmltv/threadfin.xml on that port.

Why doesn't Plex find Threadfin automatically?

Plex discovers HDHomeRun tuners with a network broadcast that does not reach a Docker container in the default bridge mode. Enter the server's IP address and port 34400 manually in the Plex DVR setup.

Should I pick XEPG or PMS in the Threadfin wizard?

Pick XEPG. It lets Threadfin match channels to your XMLTV guide. The PMS option relies on Plex's own lineups, which do not cover most IPTV channels.

How many tuners should I set?

Set the tuner count to the number of simultaneous streams your subscription allows. A higher number lets Plex start streams the provider will refuse.

Do I need Plex Pass for this?

Not to watch live channels at home. Recording requires Plex Pass, and watching away from home requires Plex Pass or Plex's Remote Watch Pass.

Can I run Threadfin without Docker?

Yes. Threadfin publishes binaries for Windows, macOS and Linux, and some NAS systems offer it as an app. The Plex side of the setup is identical.

Will my settings survive an update?

Yes, as long as the conf folder is mounted as a volume. Pulling a new image and recreating the container keeps your mapping.

Menu names in Plex Web and Threadfin's settings pages change between versions, and Plex's pricing and remote-playback rules can change. Prices are US list prices at the time of checking. Checked October 2026.