dopeIPTV Help

dopeIPTV is a free, open-source desktop IPTV player for Xtream Codes and M3U playlists. It gives you a full EPG guide, live timeshift and catch-up TV, one-click recording, and multiview for up to nine channels at once — all in one native app built on the mpv engine.

Yes. dopeIPTV is completely free and open source under the GPL-3.0 licence, with no ads, no tracking and no account required.

No. dopeIPTV is only a player — it does not provide, sell or host any channels or content. You connect your own Xtream Codes, M3U or Stalker provider.

dopeIPTV is built for Linux and also runs on macOS and Windows. Linux ships as an AppImage and a .deb (for x86_64 and ARM64) and as a Flatpak; macOS as a .dmg for Apple Silicon and one for Intel Macs; and Windows as a portable build for x64 and ARM64.

dopeIPTV is translated into these 27 languages. Arabic, Hebrew, Persian and Urdu mirror the whole layout, right to left.

• English
• العربية
• 中文
• Hrvatski
• Nederlands
• Français
• Deutsch
• Ελληνικά
• עברית
• हिन्दी
• Bahasa Indonesia
• Italiano
• 日本語
• 한국어
• فارسی
• Polski
• Português (BR)
• Русский
• Srpski
• Español
• Kiswahili
• Svenska
• ไทย
• Türkçe
• Українська
• اردو
• Tiếng Việt

Three formats, all self-contained — Python, Qt, libmpv and ffmpeg are inside the download, so there is nothing to install alongside it.

AppImage — the one to take if you are not sure. It runs on any distribution:

chmod +x dopeIPTV-*.AppImage
./dopeIPTV-*.AppImage

.deb on Debian or Ubuntu:

sudo apt install ./dopeiptv_*_amd64.deb

Flatpak:

flatpak install --user dopeIPTV-*.flatpak

The AppImage and the .deb also come as arm64 builds, for a Raspberry Pi or an ARM server.

Open the .dmg and drag dopeIPTV to Applications. There is one for Apple Silicon, which needs macOS 15 or later, and one for Intel Macs, which needs macOS 14 or later.

The first launch is refused because the app is not notarised by Apple. Close the message, open System Settings → Privacy & Security, scroll down to the note about dopeIPTV and click Open Anyway, then confirm with your password. From then on it opens like any other app. See “macOS says the app cannot be opened” below if that does not clear it.

There is no installer. Unzip dopeIPTV-*-windows-x64.zip anywhere you like — your user folder is fine, no admin rights needed — and run dopeiptv.exe inside it.

There is a native arm64 build for Snapdragon laptops; the x64 one also runs there under emulation, just slower.

For a Start-menu or desktop shortcut: Settings → Advanced → Create shortcut. The README.txt in the zip lists everything to delete if you want the app gone without a trace.

On first launch you are asked for three things from your Xtream Codes account:

• Server — the address with the port, like http://example.com:8080. Not a full playlist URL, just the host.
• Username and Password — the ones your provider gave you.

They are saved. To add another account later, or edit this one: Settings → Playlists. You can switch between playlists while the app is running, and favourites and history are kept separately for each.

Got an M3U address, or a portal address with a MAC address, instead? See the next two answers.

Yes. Choose M3U when adding a playlist and paste the URL your provider gave you.

An Xtream account gets more out of the app — catch-up, account expiry, the provider's own guide — because those come from an API an M3U list does not have. An M3U list plays and can be given its own XMLTV guide address, which covers most of the gap.

That is a Stalker / Ministra portal. When adding a playlist, choose Stalker / Ministra portal as the type, paste the portal address and enter the MAC address your provider registered, like 00:1A:79:12:34:56.

Channels, films, series and the guide's now and next work. Portal support is still experimental, and catch-up from a portal is not there yet.

Yes. The setup wizard offers demo channels: a handful of free, public test streams from Mux, Apple and Bitmovin, so you can see the app work before typing anything in. They are official test assets, not anybody's TV service, and you can switch to a real playlist whenever you like.

Your settings, playlists and favourites are kept whichever way you update.

AppImage — from 1.2.15 on it updates itself. When a new version is out, a banner in the app offers Update now, and so does About dopeIPTV: the app downloads the new version, checks it, test-starts it and swaps it in, then offers to restart. With an older AppImage, download the new one, make it executable, delete the old file and start the new one — the menu entry follows it.

.deb and Flatpak — install the new file the same way as the first time (by its full name if the old one is still in the folder). It replaces the old version.

Windows — close the app, delete the old dopeiptv folder and unzip the new one in its place.

macOS — drag the new dopeIPTV to Applications and choose Replace. If macOS refuses the first start, allow it again with Open Anyway under Privacy & Security.

Double-click it in the middle list, or press ▶ Play in the panel on the right. Picking another channel switches the stream in place rather than tearing the player down and building it again, which is what makes zapping quick.

The Back and Next buttons in the player bar move through whatever list you are in — channels, a series' episodes, recordings or history.

For films, episodes, recordings and catch-up — anything with a known length:

• Move the pointer over the picture and a scrubber slides up, with the timeline, the elapsed and total time, and −10s / +30s buttons.
• Click the video once and use the arrow keys: a tap jumps ten seconds, holding one down seeks continuously.

Live channels have a rewind bar of their own — see the next answer.

Yes, on any live channel. Move the pointer over the picture and a bar takes you back; pause and the arrow keys work too, and LIVE brings you back to now.

How far back is set under Settings → Playback → Rewind live channels: a couple of minutes in memory by default, or up to six hours with Keep the rewind buffer on disk.

Rewind with dopeIPTV's own buffer (experimental) goes further: the app keeps the channel itself on disk and goes on downloading while you pause, so LIVE never has to reconnect, and a channel you leave keeps its history until you close the app. On a channel with the provider's catch-up, DVR | TIMESHIFT at the left of the bar switches between this buffer and the archive.

Double-click the picture, or press F. Esc leaves it — and so does the explicit Exit fullscreen button in the floating control bar, which is there so nobody has to know about Esc.

The controls and the mouse pointer hide themselves after a few seconds of stillness and come back on the smallest movement.

Yes — pop the player out into its own window and drag it wherever you like.

It is frameless by default: drag anywhere on the picture to move it. Right-click for always-on-top, a title bar, or Exit. Esc also brings it home. The main window keeps working while it is out.

The ⚙ button in the player bar — it is in the fullscreen controls too — holds everything about the stream you are watching:

• Audio track and subtitle track
• Audio delay, when the sound is out of step
• Aspect ratio (16:9, 4:3, stretch and so on)
• Network buffer size
• Stats for nerds: codecs, resolution, frame rate, hardware decoding, A/V sync, dropped frames, cache and network speed, live over the picture

A track you pick is remembered, and for a series it carries over to the next episode. To set a preference for every stream instead, see Settings below.

• Space — pause and resume
• F — fullscreen, Esc to leave
• ← / → — seek ten seconds, hold to keep going
• M — mute

They work in the main window, in fullscreen and in the popped-out window alike.

Yes, for films, series episodes, recordings and your own local files. Starting one again asks whether to resume at that point or start from the beginning.

Positions very close to the start or the end are ignored on purpose, so it does not offer to resume something you had only just begun or had actually finished.

From your provider. Every live channel in the list shows what is on now with a progress bar, and the detail panel shows what is next.

The guide is cached on disk for each playlist, so it is on screen the moment you start the app — the fresh copy downloads in the background and replaces it. If that download fails, the cached guide stays rather than leaving you with nothing.

Yes. The Guide button in the sidebar opens a searchable programme grid covering every channel, with a timeline you can scroll through. Search finds a programme by name across all channels.

On a channel with catch-up, double-clicking a programme that has already aired plays it from the archive.

Give that playlist its own guide instead of the provider's:

1. Settings → Playlists
2. Select the playlist and edit it
3. Put an XMLTV URL in the custom guide field

It replaces whatever the provider sends. The app matches your channels to that guide by EPG id first and by channel name second, so a guide from a different source usually still lines up.

Some providers publish times that do not match what they actually broadcast. Two separate corrections live in Settings → Guide:

• EPG delay shifts every time the guide displays.
• Replay delay shifts where catch-up and timeshift start playing, without touching the listings.

They are separate because providers get these two wrong independently of each other.

Some providers keep a recording of each channel for a few days. Where yours does, the channel gets a ⏪ marker in the list, and the detail panel says how many days deep the archive goes.

If a channel has no marker, the provider is not offering an archive for it. That is their setting and nothing in the app can turn it on.

Press the ⏪ button in the player — it is in the fullscreen controls too — or right-click the channel and choose Timeshift. Then pick from the start.

What plays is a piece of the archive, so it seeks like a film: the scrubber and the arrow keys both work inside it.

Yes. The timeshift menu lists past programmes grouped by day — double-click one to watch it. You can also jump back in fixed steps, and those steps scale to how deep your provider's archive actually is, from thirty minutes up to a week.

Some providers accept an archive request and quietly serve the live feed instead. The app checks and tells you when that happens rather than letting you think you are watching yesterday.

Two ways in:

• The REC button in the player, for what you are watching now.
• Right-click any channel → Record, for one you are not watching.

Unless you choose a length it records until you stop it. You can watch a recording while it is still being written.

While you pause, a recording taken from the player's stream stands still as well, and the app tells you so. With dopeIPTV's own buffer turned on, Record records from the buffer instead: whole while you pause, and from where you are when you have gone back.

Yes to both. The REC menu offers 30 minutes, 1, 2 or 4 hours, and a scheduled recording takes a start and a stop time.

Scheduled jobs survive restarting the app, but the app has to be running when they fire — it is a program, not a background service. Recordings → Active & scheduled shows what is pending.

Not if you record the channel you are watching: that taps the player's own stream, so it costs nothing extra and works on the usual accounts that allow only one stream at a time.

Recording a different channel, or a scheduled job starting later, does open its own connection to the provider.

One thing to know about an in-player recording: it is finalised when the recording stops, so stopping playback, zapping to another channel or a stream error ends it.

Yes, at two levels. Settings → Recording takes a size limit that applies to every recording — a number plus MB, GB or TB. And the player's REC menu has a quick limit for the current session only, from 250 MB to 10 GB.

Wherever you set under Settings → Recording. The Recordings section in the sidebar browses them, with subfolders as categories: create folders, rename, move things between them, and select several to delete at once.

A separate window showing 2, 4, 6 or 9 live channels at once in a grid, each one an independent stream. They can come from different playlists and even different accounts.

Open it from the sidebar; the grid size is under Settings → Multiview. Double-click a window to maximise it.

Click a window to give it the audio — a red border marks the one you are hearing.

Right-click any window for: mute, audio and subtitle track, move or swap it with another, or remove it. A channel with catch-up gets its own archive timeline inside its window, so you can rewind one channel while the others stay live.

Because it does — one per window. Most IPTV accounts allow only one or two streams at a time, so a nine-window grid will simply be refused by most providers.

The app says this once, before you find out from a wall of failing streams. If you see “connection limit reached”, this is usually why.

Right-click a channel, film or episode → Cast to TV…, then pick the device. Chromecasts and smart TVs are in the same list: a TV that speaks DLNA/UPnP — Samsung, LG, Sony, Philips, Panasonic and many others — is marked (DLNA). A Chromecast gets live channels as HLS, which is what a Cast receiver expects; a TV fetches the stream as it is.

Casting stops local playback — the two would be a second connection to your provider. A strip above the player names the device and what is on it, with a stop button. Playing something in the app also ends the cast and hands playback back.

Some channels are ordinary H.264 video with Dolby Digital Plus audio. A Chromecast that is not an Ultra or a Google TV has no decoder for that and rejects the stream without saying why.

The app converts those on this computer and serves the result on your own network: the video is copied through untouched — only the audio is re-encoded, which is cheap — and it only happens after the device has actually refused the stream. A channel your device can play always gets the provider's own stream, unaltered.

This needs ffmpeg, which is inside every packaged download.

While it plays, open the player's Subtitles menu → Find subtitles online…. The app searches OpenSubtitles.com for what you are watching, in your subtitle language, and lists the matches — one made for exactly that file first. Pick one and it shows straight away; the next time you play the title it comes back by itself.

If the app asks for an API key: sign in at opensubtitles.com, open API consumers, create a key and enter it under Settings → Audio & subtitles. Signing in with your OpenSubtitles account there is optional and raises how many subtitles you can download a day. A subtitle file you already have loads with Load subtitle file… in the same menu.

How many: without an account, OpenSubtitles lets each internet connection download 5 subtitles a day; with a free account entered under Settings → Audio & subtitles, 20 a day. Searching never counts, and a subtitle you have downloaded stays on your computer, so playing it again costs nothing. When the day's downloads are used up, the app says so — try again the next day.

Settings → Trakt → Connect via browser. Your browser opens Trakt: sign in if you are not already, click Yes, and the app is connected. There are no keys to create and no code to type.

After that, what you watch is scrobbled, and your watchlist and history can be browsed inside the app. Your own local files are scrobbled too, whenever TMDB could identify the file.

Yes. Local files in the sidebar browses folders you add under Settings → Local files.

A network share your system has already mounted appears by itself — a gvfs SMB mount on Linux, a share under /Volumes on macOS, a mapped drive on Windows. These are ordinary paths as far as the app is concerned, so there is no SMB client inside it to misbehave.

Both, toggled in the middle column.

• Folders shows the tree exactly as it is on disk.
• Library reads the file names and builds series with seasons and episodes out of them, with films under Movies — the same shape as the provider's own sections.

TMDB, for anything that can be matched by name and year. What cannot be matched gets a frame grabbed from the video itself, and music gets its cover from the file's tags or a cover image in the folder.

A file with no year and no release tag in its name is never guessed at. That is deliberate: a wrong poster is worse than a thumbnail. Rename the file to include the year if you want it matched.

Yes. Albums are shelved together, artist, album and title come from the tags, and there is a play queue: add a track, queue a whole folder, or play something next. It moves to the next track by itself when one ends.

There is also a visualiser and a ten-band equaliser.

It has been moved, renamed, or its share is not mounted. History says which, and offers to remove the entry, instead of failing silently.

If it is a share, mount it and try again — the entry will work as it did before.

Settings → General. The interface is translated into 27 languages and switches immediately, with no restart. Arabic, Persian, Hebrew and Urdu mirror the entire layout.

Settings → Appearance: themes, light and dark, picked from small pictures of the app; an accent colour, or any colour you like; following the desktop's light and dark mode; corner style and the size of text and controls — all applied live.

Settings → Playback, Audio & subtitles and Video set what should happen without you asking each time:

• Preferred audio language
• Subtitles on or off, with a first and second preferred language
• Default aspect ratio and network buffer
• How early the “Next episode” card appears — off, or one to ten minutes

The ⚙ menu in the player still overrides any of these for the stream you are watching.

How far back live channels can be rewound is set on the Playback page too.

Yes. A PIN protects locked categories and locked favourite groups. A locked group does not reveal which channels are in it until the PIN is entered — hiding the contents, not just the playback.

The PIN is stored salted and hashed, not in plain text.

Right-click any channel, film or series to rename or hide it. The result is effectively your own edited playlist, saved per playlist, and Restore default channels… puts everything back exactly as the provider sends it.

Whole categories can be hidden, renamed or locked from the category right-click menu. A hidden category's channels are left out of “All” as well.

Add as many playlists as you like under Settings → Playlists and switch between them while the app runs. Each one keeps its own favourites, history, hidden channels and renames.

Each can also have its own XMLTV guide URL and its own refresh schedule — never, at startup, every 2, 6 or 12 hours, daily or weekly.

The start page. At the top, this week's most popular films and series that your provider has, with Play and More info; below, what you were watching with the time left, your favourite channels with what is on now, new episodes of the series you follow, the popular charts and what your provider added lately.

Each section can be turned off under Settings → Home, and so can Home itself.

Yes. Settings → General → Update channel → Test builds offers each test build of the next version as soon as it is made, in the same update banner — and on the AppImage with the same one-click update. Test builds can have faults a release does not.

Back on Releases, you keep the test build until the next release comes out.

The log is what turns “it does not work” into something fixable, and credentials are masked out of it automatically, so it is safe to attach to an issue.

Run the app from a terminal with DOPEIPTV_LOG_FILE set and it writes one there as well as to the screen.

Linux — AppImage

DOPEIPTV_LOG_FILE=/tmp/dopeiptv.log ./dopeIPTV-*.AppImage

Linux — .deb or pipx

DOPEIPTV_LOG_FILE=/tmp/dopeiptv.log dopeiptv

macOS

DOPEIPTV_LOG_FILE=/tmp/dopeiptv.log \
  /Applications/dopeIPTV.app/Contents/MacOS/dopeiptv

Windows — PowerShell, in the unzipped folder

$env:DOPEIPTV_LOG_FILE="$env:TEMP\dopeiptv.log"
.\dopeiptv.exe

Reproduce the problem, close the app, and attach the file. For much more detail add DOPEIPTV_LOG=debug in front of the same command.

Start it from a terminal — see the answer above for the exact command on your system — and read what it prints. That names the cause far more often than not.

The packaged builds carry everything they need. If you installed from source with pipx you also need mpv and ffmpeg from your distribution:

sudo apt install mpv ffmpeg     # Debian/Ubuntu
sudo dnf install mpv ffmpeg     # Fedora
sudo pacman -S mpv ffmpeg       # Arch

The embedded player is not getting a video surface.

1. Open ⚙ → Stats for nerds and see whether frames are arriving at all — that separates a stream problem from a display one.
2. On Wayland, try Settings → Advanced → Run via X11 backend and restart the app.
3. Run from a terminal and look for lines mentioning GL or mpv.

It is not notarised by Apple yet, and since macOS 15 right-clicking the app and choosing Open no longer gets past that. Open System Settings → Privacy & Security, scroll down to the note about dopeIPTV and click Open Anyway, then confirm with your password. The button is there for about an hour after the app was refused — if it is missing, start the app once more.

If macOS instead says the app is “damaged”, that is the quarantine flag from the download. Clear it in Terminal:

xattr -dr com.apple.quarantine /Applications/dopeIPTV.app

Neither warning means anything is wrong with the app — only that the build is not code-signed, which needs a paid Apple certificate.

SmartScreen does not recognise the publisher, because the build is not code-signed — that needs a paid certificate. Click More info, then Run anyway.

A false positive. Two of its causes were fixed in 1.2.10: the launcher is now compiled from source instead of being the stock prebuilt one that antivirus engines hold signatures for, and the executable carries a proper version resource.

If your engine still flags it, allow the folder in your antivirus and report the false positive to Microsoft — that is what eventually clears it for everybody, not just for you.

Wrong username or password.

The provider turned the details down. It is almost always a slip when they were typed or copied:

1. Username and password are case-sensitive.
2. A space came along when you copied them — remove it at the start or end.
3. The server address often needs its port, such as http://example.com:8080. Use exactly what your provider sent.
4. Got an Xtream or M3U link? Paste the whole link into Server and the app fills in the rest.
5. On a MAC portal the MAC address must be the one your provider registered.

The app probes the provider and tells you why in plain language rather than showing a bare failure: account expired, connection limit reached, stream missing, server unreachable, and so on.

If other channels play, it is that channel. If nothing plays, check Settings → Playlists — the account panel shows the expiry date and how many connections the account allows.

The provider keeps cutting the stream — if this account is playing on another device or app, close it there.

Almost always the same account is playing somewhere else at the same time — a TV, a phone, another app, or someone you share it with. The provider allows only so many streams at once, so the two take turns: it cuts one off to let the other in, again and again.

Close the stream on the other device and the picture runs smoothly again. When every connection is taken before you even start, the app says so instead:

All 2/2 connections are in use — close the stream on your other device or app

Your account allows a certain number of streams at the same time and they are all in use. In order of likelihood:

1. Multiview is open — each window is a connection.
2. A recording of a different channel is running.
3. Another device or another person is using the account.
4. A previous session has not timed out yet at the provider; waiting a minute often clears it.

Recording the channel you are watching does not count as a second connection.

Your subscription has expired — renew it with your provider

The provider has ended the account, so nothing plays. Settings → Playlists shows the expiry date. Renew with your provider and the playlist works again — there is nothing to add again in the app.

If the provider has disabled the account, the app says that too; only the provider can turn it back on.

The provider blocked this stream (HTTP 458) — usually anti-VPN/re-streaming, a connection limit, or a region/device block. Turn off any VPN and check with your provider.

Many providers turn away VPNs and data centres, since that is how accounts get resold. Turn the VPN off — or leave dopeIPTV outside it, if your VPN lets you choose apps — and try the channel again.

No VPN on? Then ask your provider: the account may be locked to one country, device or address.

This stream hasn't started yet — it looks like an upcoming event. Try again once it's live.

Sports and pay-per-view channels are often empty until the event begins. Nothing is wrong with the account or the app — try again once it is live. The channel name usually says when it starts.

On Wayland, GNOME and KDE take a window's icon from a desktop entry matching it and ignore what the application sets for itself. An AppImage has no such entry until something installs one.

1. The app offers to add one the first time it starts. Say yes — then restart the app, because the window you are looking at keeps the icon it opened with.
2. The same switch is under Settings → General if you said no.
3. If the icon still does not appear, a stale icon cache is hiding it. GTK reads that file instead of the folder:

rm ~/.local/share/icons/hicolor/icon-theme.cache

Installed from the .deb, the entry is already there and none of this applies.

That option launches a standalone mpv or vlc from your system, so one of them has to be installed — the built-in player needs nothing extra and is unaffected.

sudo apt install mpv vlc        # Debian/Ubuntu
sudo dnf install mpv vlc        # Fedora
sudo pacman -S mpv vlc          # Arch

dopeIPTV is free and open source under the GPL-3.0 licence — no ads, no tracking, no accounts. It's built with, and grateful to, these projects and services:

• Playback — mpv & FFmpeg, via python-mpv
• Interface — Qt & PyQt6
• Casting — PyChromecast — Google Cast
• Metadata & artwork — The Movie Database (TMDB)
• Watched sync — Trakt
• Licences — GPL-3.0 & third-party

This product uses the TMDB API but is not endorsed or certified by TMDB. This product uses the Trakt API but is not endorsed or certified by Trakt. All trademarks are the property of their respective owners.

No. dopeIPTV has no ads, no tracking and no accounts. Metadata and artwork come from TMDB and optional watched-history sync uses Trakt — both only if you choose to use them.