m3u4me: Self-hosted M3U playlist manager

m3u4me is your IPTV playlists' new home. Your streams don't leave your local network, you are in charge, nobody can see or control your playlists.

[!WARNING] m3u4me does NOT provide ANY streams! It is purely a M3U playlist manager. You must bring your own content.

[!NOTE] This app aims to be a self-hosted alternative to https://m3u4u.com/ - as you can see, m3u4me's name is obviously referencing them. The projects are not related in any way. No harm intended!

AI Disclosure

[!NOTE] This app's code was AI-generated, with minor interventions from me. I am a graphic designer with very limited coding knowledge; I do not support pointless usage of AI and I am fully aware of the harm it can cause.

m3u4me started out as something that was intended only for personal use - I am sharing it only because I believe it is an useful app which might help many other IPTV enthusiasts. It will always be entirely free.

I fully encourage any developer who comes across this app and wants to turn it into something human-made, without AI involvement.

AI was not used for anything else besides writing the actual code of the app.

Features

• Guided setup: The first time you open m3u4me, a short setup walks you through adding your provider and TV guide, an optional password, and your first playlist. Moving from another m3u4me? Restore your backup right from the welcome screen.
• Multiple playlist support: Add as many playlists as you like. Start empty or import an M3U or XSPF playlist from a URL or an uploaded file.
• Channel pool sources: Connect your Xtream Codes account, a playlist URL, or an M3U/XSPF file; then browse, search and add channels into any playlist. Each source refreshes on its own schedule and keeps a changelog of what got added, removed or renamed. If a provider only works with certain apps, choose which app the source downloads as (TiviMate, VLC, Kodi, a browser, or your own user agent). When a download fails, the source tells you why in plain words and what to try, and keeps showing it until a download works.
• Channel sync: When you add channels from an Xtream Codes or playlist URL source, you can keep them in sync with that source. Choose what updates automatically (stream link, name, logo, TVG ID), per selection or per channel, and set your defaults in Settings. If you changed something yourself, the provider's update waits for you to accept or skip it. Channels that disappear from their source are hidden and marked, and every playlist has a sync log. Channels already in a playlist can be linked too.
• EPG guide: Add EPG sources from an XMLTV URL or an Xtream Codes account, each on its own refresh interval. Browse a live programme timeline and assign TVG IDs to your channels by hand, in bulk via automatic fuzzy name-matching, or one by one.
• Logo editing: Add/edit/remove your channels' logos.
• Stream checker (Not recommended): Basic stream checking functionality, not recommended due to some IPTV providers not reacting nicely to any sort of bulk checking. Use at your own risk!
• Bulk actions: Move, delete, find & replace, or check multiple channels at once. Hide a whole category from your playlist with one click on its eye button.
• Auto-saving: You don't need to remember to save your changes or push your playlist. Everything happens instantly, automatically.
• Undo delete: Deleted a channel by mistake? Hit the "Undo" button which appears on the bottom of your screen and bring it back without a hassle.
• Simple playlist link structure: No more typing huge links on your TV. Playlists get assigned a numerical ID, which means that your download links look like this: http://IP:port/1 for your first playlist, http://IP:port/2 for the second one, and so on. Each playlist also gets its own EPG feed at http://IP:port/{number_ID}/epg.
• Printable channel list: Turn any playlist into a neat A4 channel list PDF, with numbers, logos, names and whether each channel has a TV guide. Press "PDF" in the playlist's toolbar, check the preview, then "Save PDF" and choose "Save as PDF" in the print window.
• Backup & restore: Download everything (playlists, sources, TV guides and settings) as one file from Settings, then restore it on the same server or a new one.
• Global search: Search across every playlist, channel pool source, and EPG source at once. All searches ignore accents, so typing "stiri" also finds "Știri".
• Keyboard shortcuts: Delete your channels with DEL, select everything with Cmd+A, make your work easier overall. Full list of commands is available inside the app.

Cosmetic UI features:

• Light mode, Dark mode & AMOLED Dark mode
• Custom accent colours: Even the browser tab's favicon matches your chosen colour.
• Channel logo background colour presets: Choose between light gray, white, black or transparency. (Only for previewing. Does not affect the actual logos in the playlist.)
• Hide stream URLs: Useful for sharing screenshots.
• 12-hour or 24-hour time: Pick your preferred clock format for the EPG guide.

Installation

[!NOTE] m3u4me has been tested on macOS (Apple Silicon) and Debian, running with as little as 512MB of RAM.

There are three ways to install m3u4me. The first one is by far the easiest. Once it's running, open it in your browser and a short setup walks you through the rest.

Option 1: One-line install (recommended)

For Linux servers running systemd that install software with apt or dnf: Debian, Ubuntu, Fedora, and Proxmox containers based on them.

curl -fsSL https://raw.githubusercontent.com/andrei-savin/m3u4me/main/install.sh | sudo bash

This command installs Node.js if it is missing, downloads the latest release, builds the app, and sets it up to start automatically whenever your server boots. When it is done, it prints the address where you can open m3u4me.

To use a port other than 8080:

curl -fsSL https://raw.githubusercontent.com/andrei-savin/m3u4me/main/install.sh | sudo PORT=9090 bash

(Obviously, replace 9090 with your desired port.)

This only works on the first install. To change the port later, edit /etc/m3u4me.env and run sudo m3u4me restart.

[!NOTE] Piping a script into sudo bash means trusting it. install.sh is deliberately commented so you can read the whole thing first. Here is everything it changes on your system:

• Installs git and curl if they are missing.
• Installs Node.js if it is missing or too old. It comes from NodeSource, whose package repository is added to your system so Node.js keeps getting updates.
• Puts m3u4me in /opt/m3u4me and runs it as a locked-down m3u4me user, through one systemd service.
• Saves the port in /etc/m3u4me.env and adds the m3u4me command to /usr/local/bin.

Once it is installed, you get an m3u4me command:

Your playlists live in /opt/m3u4me/data, and the port setting lives in /etc/m3u4me.env.

Option 2: Docker

git clone https://github.com/andrei-savin/m3u4me.git
cd m3u4me
docker compose up -d

m3u4me will be running at http://localhost:8080. Your playlists are stored in the data folder next to docker-compose.yml. To use a different port, change it in docker-compose.yml and run the last command again.

Option 3: Manual, with PM2

The original way to run m3u4me. Use this if you would rather set everything up yourself.

1. Install Node.js
m3u4me needs Node.js 22.18 or newer. The official website is pretty straightforward about installing it: https://nodejs.org/en/download.
After installing, make sure it worked by running node -v in your terminal — it should print v22.18.0 or higher.

2. Install PM2
This keeps your app running 24/7 in the background.

npm install -g pm2

3. Clone the source via git:

git clone https://github.com/andrei-savin/m3u4me.git

4. Navigate into the folder:

cd m3u4me

5. Install the dependencies:

npm ci

m3u4me runs on port 8080 by default. You can change that in ecosystem.config.cjs.

6. Build the app:

npm run build

7. Start up PM2:

pm2 start ecosystem.config.cjs

All done! You can now use m3u4me at http://localhost:8080 [replace localhost with the IP of your server, and 8080 with whatever custom port you set up earlier].

8. Make m3u4me auto-run at startup (optional):

pm2 startup
pm2 save

Updating

If you used the one-line install

sudo m3u4me update

That is the entire update. It fetches the newest release, rebuilds the app, restarts it and checks that it is running. If the new version fails to build or does not start, it automatically puts the previous version back.

If you use Docker

git pull --ff-only
docker compose up -d --build

If you installed manually with PM2

1. Navigate into the app's folder

[!NOTE] The folder shown in the command below is only an example.

cd /opt/m3u4me

2. Pull the latest code from this repo

git pull --ff-only

[!NOTE] During this step, you might run into the following error: Your local changes to the following files would be overwritten by merge. / package-lock.json / Please commit your changes or stash them before you merge. If so, just run git restore package-lock.json and then continue with the following steps.

3. Install any new dependencies

npm ci

4. Rebuild the app

npm run build

5. Restart the PM2 process

pm2 restart ecosystem.config.cjs --update-env

Backups & moving to a new server

In m3u4me, open Settings → Backup → Download backup. That one file holds your playlists, sources, TV guides and settings. It also holds your providers' logins, so keep it private. Your m3u4me password is not part of it.

To restore a backup:

• On a new server: install m3u4me, open it, and choose Restore a backup on the welcome screen.
• On a server that's already set up: open Settings → Backup → Restore from backup. This replaces everything m3u4me has now. Just in case, a copy of the replaced data stays in m3u4me's data folder, named db.json.before-restore- followed by the date and time.

[!NOTE] Older versions of m3u4me don't have the Download backup button. Use the db.json file from the old server's data folder instead: /opt/m3u4me/data for the one-line install, or the data folder inside the m3u4me folder for Docker and PM2.

Bug reports & feature requests

If you encounter any AI slop, or other sort of error, feel free to create a GitHub issue. I will reply ASAP.
You can also open issues for any feature requests. However, I can not guarantee that they will be accepted.