How to Use Docker to Run a Private IPTV Proxy Server

Your IPTV provider gave you a long M3U URL or an Xtream Codes API link. You paste it into TiviMate or IPTV Smarters Pro and it works. But every time you open the app, your device connects directly to your provider’s server. That URL contains your username and password in plain text. Anyone who inspects your network traffic can see it. Your provider’s server is exposed to the internet with no layer between you and them. If your provider changes their domain, you have to update every device manually. If you have two IPTV subscriptions, you cannot combine them into one clean playlist.

There is a better way. A Docker IPTV proxy server sits between your IPTV player and your provider. It receives requests from your player, forwards them to the provider, and sends the stream back. Your player never talks to the provider directly. This protects your credentials, lets you combine multiple sources, adds authentication, filters channels, and even wraps everything in HTTPS with your own domain. In this step-by-step tutorial, you will learn exactly how to use Docker to run a private IPTV proxy server at home. You will set up two different proxy solutions, add HTTPS with Traefik, filter channels, and connect your favourite IPTV player. All of this runs in Docker containers that take minutes to deploy. Perfect IPTV subscriptions work seamlessly with Docker proxies, giving you 9,000+ channels through your own private infrastructure.

What Is a Docker IPTV Proxy Server?

An IPTV proxy server is a middleman between your streaming device and your IPTV provider. Instead of connecting directly to your provider’s server, your device connects to the proxy. The proxy forwards the request, fetches the stream, and sends it back to your device. Your provider never sees your real IP address. Your device never sees your provider’s real URL. The proxy acts as a shield.

Running this proxy in Docker means you package the entire proxy application into a lightweight container. Docker handles dependencies, networking, and configuration. You do not install anything directly on your host system. One command starts the proxy. Another command stops it. Updates are a single pull and restart away.

Why Run an IPTV Proxy in Docker?

There are five main reasons people use Docker to run a private IPTV proxy server. First, credential protection. Your M3U URL or Xtream Codes API link contains your username and password. When you paste it into an IPTV player app, that app now knows your credentials. If the app phones home or if someone inspects the app’s traffic, your credentials are exposed. A proxy hides the original URL so your player only knows the proxy address. Second, provider URL masking. If your provider changes their server domain or IP, you update the proxy configuration once. All your devices keep working because they point to the proxy, not the provider directly. Third, multi-source merging. You can combine two or more IPTV subscriptions into a single playlist. The proxy handles failover if one source goes down. Fourth, channel filtering. Remove adult channels, unwanted groups, or duplicate entries before they reach your player. Fifth, HTTPS encryption. Add a Let’s Encrypt certificate through Traefik or Nginx and access your proxy securely over HTTPS. Your ISP cannot see what you are streaming.

Trial Pass

How an IPTV Proxy Works

The proxy downloads your M3U playlist or connects to your Xtream Codes API. It rewrites all the stream URLs to point to itself instead of the original provider. When your IPTV player requests a channel, the proxy fetches the stream from the provider and relays it. The entire process adds minimal latency. Most proxies add less than 10 milliseconds to your stream startup time. The stream data itself is not cached or stored. It passes through the proxy byte by byte. Once the stream ends, no data remains on the proxy server. This makes the proxy efficient enough to run on a Raspberry Pi, an old laptop, or a cheap VPS.

Choosing the Right Docker IPTV Proxy Solution

There are several open-source Docker IPTV proxy projects available. Two stand out as the most popular and actively maintained. Each serves a different use case.

Option 1: iptv-proxy by pierre-emmanuelJ

This is the most popular Docker IPTV proxy on GitHub with over 690 stars. It is written in Go and supports both M3U/M3U8 playlists and the Xtream Codes client API. It supports live TV, video on demand, series, and full EPG proxying. The proxy rewrites all stream URLs to point to itself. You get a clean M3U file with endpoints that map back to your proxy server. It includes authentication support and can run behind Traefik for automatic HTTPS certificates. The Docker image is small and efficient at around 20 MB. This is the best option if you have a single provider using either M3U or Xtream Codes and you want a simple, lightweight proxy.

Option 2: m3u-stream-merger-proxy by sonroyaalmerol

This proxy serves a different purpose. It merges multiple M3U playlists from different providers into a single consolidated playlist. It includes built-in load balancing that cycles through available stream URLs. If one provider’s stream fails, it tries the next one. It also merges EPG data from multiple sources, filters channels by group or title, and supports credential-based authentication with optional expiry dates. The project is under active development with over 175 stars and a Docker image that gets updated regularly. This is the best option if you have two or more IPTV subscriptions and want to combine them into one playlist with automatic failover.

Perfect IPTV UK Pricing Plan

Prerequisites

Before you begin, make sure you have the following ready. A server or computer running Linux, Windows with WSL2, or macOS with Docker installed. You need Docker Engine and Docker Compose. If you do not have them, install Docker Desktop from the official Docker website. For a home server, a Raspberry Pi 4 or 5 with 2 GB of RAM is enough for most IPTV proxy setups. You need an IPTV subscription with either an M3U URL or Xtream Codes API credentials. If you do not have one yet, start a free 3-hour trial with Perfect IPTV to follow along. You also need basic familiarity with the command line and a text editor for editing docker-compose files.

Step 1: Set Up iptv-proxy for M3U Playlists

Create a new directory for your proxy setup. Inside it, create a file named docker-compose.yml. Paste the following configuration.

version: "3"

services:
  iptv-proxy:
    image: pierremn/iptv-proxy:latest
    container_name: iptv-proxy
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - M3U_URL=http://your-provider.com:1234/get.php?username=USER&password=PASS&type=m3u_plus&output=m3u8
      - PORT=8080
      - HOSTNAME=192.168.1.100
      - USER=proxyuser
      - PASSWORD=proxypass
      - GIN_MODE=release

Replace M3U_URL with your actual provider M3U URL. Replace HOSTNAME with your server’s local IP address. Change USER and PASSWORD to something secure. These are the credentials your IPTV player will use to access the proxy. Save the file and start the container.

Limited Time Offers

docker-compose up -d

The container pulls the image and starts. Check the logs to make sure it connected successfully.

docker logs iptv-proxy

If everything is working, you will see log entries showing that the M3U file was loaded and the proxy is ready. Access your proxied playlist by opening a browser and navigating to http://192.168.1.100:8080/iptv.m3u?username=proxyuser&password=proxypass. You should see a clean M3U file where all the original stream URLs have been replaced with URLs pointing to your proxy server.

Step 2: Set Up iptv-proxy for Xtream Codes API

If your provider uses Xtream Codes API instead of a plain M3U URL, the setup is similar but requires extra environment variables. The iptv-proxy supports the full Xtream Codes client API including live TV, VOD, series, and EPG. Create a new docker-compose file with the following configuration.

version: "3"

services:
  iptv-proxy:
    image: pierremn/iptv-proxy:latest
    container_name: iptv-proxy
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - M3U_URL=http://your-provider.com:1234/get.php?username=xtream_user&password=xtream_pass&type=m3u_plus&output=m3u8
      - PORT=8080
      - HOSTNAME=192.168.1.100
      - USER=proxyuser
      - PASSWORD=proxypass
      - XTREAM_USER=xtream_user
      - XTREAM_PASSWORD=xtream_pass
      - XTREAM_BASE_URL=http://your-provider.com:1234
      - GIN_MODE=release

The XTREAM_USER, XTREAM_PASSWORD, and XTREAM_BASE_URL are your original provider credentials. The proxy rewrites them so your player uses the USER and PASSWORD values instead. Start the container.

docker-compose up -d

Once running, you can access all Xtream Codes endpoints through the proxy. For example, the live TV categories endpoint becomes http://192.168.1.100:8080/xmltv.php?username=proxyuser&password=proxypass. The player endpoint for live streams uses http://192.168.1.100:8080/live/proxyuser/proxypass/1234.ts. The proxy handles all the URL rewriting automatically. Your IPTV player only ever sees the proxy address. Your original provider URL remains hidden.

Step 3: Add HTTPS with Traefik

Running your proxy over HTTP is fine on your home network. But if you want to access it remotely or add encryption, HTTPS is essential. Traefik is a reverse proxy that integrates with Docker and automatically provisions Let’s Encrypt certificates. This setup lets you access your IPTV proxy over a secure HTTPS connection with your own domain. Create a new docker-compose file that includes both iptv-proxy and Traefik.

version: "3"

services:
  iptv-proxy:
    image: pierremn/iptv-proxy:latest
    container_name: iptv-proxy
    restart: unless-stopped
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.iptv-proxy.rule=Host(`iptv.yourdomain.com`)"
      - "traefik.http.routers.iptv-proxy.entrypoints=websecure"
      - "traefik.http.routers.iptv-proxy.tls.certresolver=mydnschallenge"
      - "traefik.http.services.iptv-proxy.loadbalancer.server.port=8080"
    environment:
      - M3U_URL=http://your-provider.com:1234/get.php?username=user&password=pass&type=m3u_plus&output=m3u8
      - PORT=8080
      - HOSTNAME=iptv.yourdomain.com
      - USER=proxyuser
      - PASSWORD=proxypass
      - GIN_MODE=release
      - HTTPS=1

  traefik:
    image: traefik:v2.10
    container_name: traefik
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./traefik-config:/etc/traefik
    command:
      - "--providers.docker=true"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--certificatesresolvers.mydnschallenge.acme.tlschallenge=true"
      - "--certificatesresolvers.mydnschallenge.acme.email=you@email.com"
      - "--certificatesresolvers.mydnschallenge.acme.storage=/etc/traefik/acme.json"

Replace iptv.yourdomain.com with your actual domain. Point the domain’s DNS A record to your server’s public IP. Traefik automatically detects the iptv-proxy container through Docker labels and provisions a Let’s Encrypt certificate. Your proxy is now accessible at https://iptv.yourdomain.com/iptv.m3u?username=proxyuser&password=proxypass with full HTTPS encryption. Your ISP, your network admin, or anyone watching your traffic cannot see what you are streaming.

Step 4: Set Up m3u-stream-merger-proxy for Multiple Playlists

If you have more than one IPTV subscription, the m3u-stream-merger-proxy is the right tool. It combines multiple M3U playlists into one, merges identical channels by name, and provides automatic failover. Create a docker-compose file with multiple M3U sources.

version: "3"

services:
  m3u-proxy:
    image: sonroyaalmerol/m3u-stream-merger-proxy:latest
    container_name: m3u-proxy
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - BASE_URL=http://192.168.1.100:8080
      - TZ=Europe/London
      - SYNC_ON_BOOT=true
      - SYNC_CRON=0 */6 * * *
      - M3U_URL_1=https://provider1.com/playlist.m3u
      - M3U_MAX_CONCURRENCY_1=2
      - M3U_URL_2=https://provider2.com/playlist.m3u
      - M3U_MAX_CONCURRENCY_2=1
      - EPG_URL_1=https://provider1.com/epg.xml
      - EPG_URL_2=https://provider2.com/epg.xml

Set BASE_URL to your server address. Add each provider’s M3U URL as M3U_URL_1, M3U_URL_2, and so on. The M3U_MAX_CONCURRENCY_X variables control how many simultaneous connections each source allows. Start the container.

docker-compose up -d

Access your combined playlist at http://192.168.1.100:8080/playlist.m3u. The proxy deduplicates channels that appear in both playlists. If provider 1 goes down, the proxy automatically tries provider 2 for the same channel. The EPG at http://192.168.1.100:8080/epg.xml is also merged from both sources. Only channel IDs that exist in your merged playlist are included, which keeps the EPG file small and fast to load.

Step 5: Filter Channels and Add Authentication

Both proxy solutions support channel filtering and authentication. With iptv-proxy, you add password protection through the USER and PASSWORD environment variables. Anyone who accesses the proxy must provide these credentials in the URL. This prevents unauthorised access even if someone discovers your proxy address.

With m3u-stream-merger-proxy, filtering is more advanced. You can include or exclude channels by group name or title using regex patterns. Add these environment variables to your docker-compose to filter out adult channels or keep only sports groups.

environment:
  - INCLUDE_GROUPS_1=^(UK|Sports|Movies|Entertainment|Documentary)
  - EXCLUDE_GROUPS_1=^XXX|^Adult|^24/7
  - EXCLUDE_TITLE_1=xxx|porn|adult|18\+

This configuration only includes channels from groups that start with UK, Sports, Movies, Entertainment, or Documentary. It removes any group that starts with XXX or Adult, and removes any channel whose title contains adult keywords. The filtering happens automatically every time the proxy syncs its playlist. You can also add authentication with expiry dates.

environment:
  - CREDENTIALS=user1:pass1|user2:pass2:2026-12-31

This creates two user accounts. The first never expires. The second expires on December 31, 2026. After that date, the second user cannot access the proxy. Set CREDENTIALS=none to disable authentication and allow open access. This is useful if your proxy only runs on your home network and you trust all connected devices.

Step 6: Connect Your IPTV Player

Once your Docker IPTV proxy is running, you need to connect your IPTV player to it instead of the original provider URL. The process is the same as adding any M3U or Xtream Codes URL, except you use your proxy address.

On TiviMate

Open TiviMate and go to Settings > Playlists > Add Playlist. Select M3U Playlist or Xtream Codes depending on your proxy setup. For M3U, enter the proxy playlist URL: http://192.168.1.100:8080/iptv.m3u?username=proxyuser&password=proxypass. For Xtream Codes, enter the proxy URL as the portal URL, then your proxy username and password. TiviMate will load the proxied playlist exactly as if it were the original. All channels, EPG data, and logos work the same way. Your provider’s real URL stays hidden inside your Docker container.

On IPTV Smarters Pro

Open IPTV Smarters Pro and go to Login. Select Xtream Codes API or M3U URL. Enter the proxy address and credentials. The app connects through your proxy. Sarah, a Perfect IPTV user from Manchester, runs iptv-proxy on a Raspberry Pi in her living room. She has her Perfect IPTV subscription proxied through Docker and uses TiviMate on three Firesticks. When her provider updated their server, she changed one line in her docker-compose file and restarted the container. All three Firesticks kept working without any changes. She has not touched a single IPTV player setting since.

Best Practices for Running a Docker IPTV Proxy

Follow these best practices to keep your proxy secure, fast, and reliable. Use a static IP address for your server. If your server IP changes, all your devices lose connection. Set a static DHCP reservation in your router or configure a static IP on the server itself. Keep your Docker images updated. Pull new versions of the proxy images regularly. Check the GitHub repositories for new releases. Updates often include security fixes, performance improvements, and new features. Run docker-compose pull followed by docker-compose up -d to update your containers.

Use strong passwords for your proxy authentication. Do not reuse your provider credentials as your proxy credentials. Generate unique, long passwords using a password manager. If you expose your proxy to the internet, always use HTTPS with a valid certificate. Traefik with Let’s Encrypt makes this automatic. Without HTTPS, your proxy credentials travel in plain text over the internet. Anyone on the same network can intercept them. Monitor your proxy logs occasionally. Check for unusual access attempts. If you see repeated failed login attempts from unknown IPs, your proxy may be under attack. Use firewall rules to restrict access to trusted IP addresses if possible. On a home network, only allow connections from your local subnet.

Back up your docker-compose files. The configuration is simple, but losing it means rebuilding from scratch. Store your compose files in a Git repository or cloud backup. If your server crashes, you can restore the setup on a new machine in minutes. Limit the number of connections if your provider has a connection limit. The M3U_MAX_CONCURRENCY setting in m3u-stream-merger-proxy prevents your provider from blocking you for having too many simultaneous streams. Set it to a value below your provider’s limit. For Perfect IPTV, the connection limit depends on your plan. A single connection plan allows one stream at a time, while the 3-connection plan allows three. Check the pricing page for your plan’s details.

Troubleshooting Common Issues

If your proxy does not work on the first try, here are the most common problems and their fixes. The container fails to start. Check your docker-compose file for typos. Make sure the M3U URL is correct and accessible from your server. Run docker logs iptv-proxy to see the error message. If the log says the M3U file could not be fetched, the URL is wrong or the provider is blocking your server IP. Try fetching the URL directly with curl from your server to verify it works.

Channels load but the stream never starts. This usually means the proxy cannot reach the provider’s stream server. Check that your server can make outbound connections on the ports your provider uses. Some providers use non-standard ports. If your server has a firewall, make sure outbound traffic is allowed. If you are using a VPS, check that the provider does not block VPS IP ranges.

EPG does not load. If you are using m3u-stream-merger-proxy, make sure your EPG URLs are correct. The proxy only includes EPG entries for channels that exist in your merged playlist. If your EPG uses different channel IDs than your M3U, use the EPG_CHANNEL_MAP environment variable to remap them. The format is m3u_tvg_id=epg_channel_id.

Streams buffer or cut out frequently. If your proxy is running on a low-power device like a Raspberry Pi, it may struggle with high-bitrate 4K streams. Try limiting the stream quality or upgrading to a more powerful server. Also check that your internet upload speed is sufficient for the number of simultaneous streams you are proxying. Each stream consumes bandwidth on both the download and upload side of your proxy. If your upload speed is 10 Mbps and you try to proxy a 4K stream that uses 25 Mbps, the stream will buffer. Consider running the proxy on a VPS with a gigabit connection if you need to proxy high-bandwidth streams remotely.

Frequently Asked Questions

Is it legal to run an IPTV proxy server?

Running a proxy for your own use is generally legal in most countries. You are routing your own traffic through your own server. The legality depends on what you stream, not how you stream it. Always use legitimate IPTV services with proper licensing like Perfect IPTV.

Do I need a powerful server for a Docker IPTV proxy?

No. A Raspberry Pi 4 or 5 with 2 GB of RAM handles multiple streams without issues. The proxy does not transcode or process video. It simply relays data packets. A 15 watt Raspberry Pi running Docker can proxy five to ten simultaneous HD streams.

Can I run the proxy on a VPS instead of at home?

Yes. Running the proxy on a VPS gives you a static public IP, fast upload speeds, and 24/7 uptime. DigitalOcean, Linode, and Hetzner all offer cheap VPS plans starting at around 5 USD per month. The proxy setup is identical to running it at home. Just make sure your IPTV provider allows connections from datacenter IP addresses.

Does the proxy slow down streaming?

The proxy adds minimal latency. Most users report less than 50 milliseconds of additional delay. The proxy does not buffer, cache, or process the video stream. It relays data packets as they arrive. For live sports and TV, the delay is unnoticeable.

Can I use a Docker IPTV proxy with Perfect IPTV?

Yes. Perfect IPTV provides both M3U URLs and Xtream Codes API credentials. Both work with iptv-proxy and m3u-stream-merger-proxy. You can proxy your Perfect IPTV subscription through Docker, add HTTPS with Traefik, and access it from any device. Plans start at just £13 per month for a single connection with a free Surfshark VPN included.

What happens if my provider blocks the proxy IP?

Some IPTV providers block known VPS IP ranges. If this happens, switch to a different VPS provider or run the proxy on your home connection. With Perfect IPTV, there are no such blocks. The service is designed to work with any legitimate IPTV player or proxy setup.

Do I need to open ports on my router for the proxy?

If you run the proxy at home and access it only from within your home network, no ports need to be open. If you want to access the proxy from outside your home, forward port 8080 (or your HTTPS port 443) from your router to the proxy server. For security, always use HTTPS with authentication when exposing the proxy to the internet.

Can I proxy both M3U and Xtream Codes at the same time?

Yes, if you use iptv-proxy. It handles both protocols simultaneously. Set both the M3U_URL and the XTREAM_* environment variables. The proxy serves the M3U playlist on one endpoint and the Xtream Codes API on another. Your IPTV player can use whichever it supports.

How do I update the proxy to a newer version?

Run docker-compose pull to download the latest image, then docker-compose up -d to restart the container with the new image. The proxy is back online in seconds. Your configuration stays intact because it is stored in the docker-compose file, not inside the container.

Does the proxy support multiple users?

Yes. Both proxy solutions support multiple user accounts. With iptv-proxy, you set a single username and password. With m3u-stream-merger-proxy, the CREDENTIALS environment variable lets you define multiple users with optional expiry dates. Each user gets their own access credentials to the same proxied playlist.

Conclusion

A Docker IPTV proxy server gives you full control over how your IPTV streams are delivered. You protect your provider credentials by hiding the original URL. You combine multiple subscriptions into a single, clean playlist. You add HTTPS encryption, channel filtering, and user authentication. All of this runs in lightweight Docker containers that you can deploy on any server in minutes. The setup works equally well on a Raspberry Pi at home or a VPS in the cloud.

The two proxy solutions covered in this guide cover most use cases. The iptv-proxy is perfect for single-provider setups with either M3U or Xtream Codes. The m3u-stream-merger-proxy is ideal for multi-provider setups with automatic failover and EPG merging. Both integrate seamlessly with TiviMate, IPTV Smarters Pro, and any other IPTV player that supports M3U or Xtream Codes.

If you do not have an IPTV subscription yet, Perfect IPTV works perfectly with both proxy solutions. You get 9,000+ live channels, 25,000+ on-demand titles, AntiFreeze Technology for buffer-free streaming, and a free Surfshark VPN with every plan. All of this can be proxied through your own Docker server for maximum privacy and control. Plans start at just £13 per month for a single connection. Claim your 3-hour free trial and start building your private IPTV proxy today. Need help with the setup? Contact the Perfect IPTV team on WhatsApp for 24/7 support.