ListPorter

A cross-platform command-line tool (Windows, Linux, macOS) for importing standard or extended .m3u audio playlists into Plex Media Server. Supports fuzzy path matching, path rewriting, and optional mirroring.

ListPorter works with playlists exported by common music players and library managers, including iTunes, MusicBee, MediaMonkey, foobar2000, Swinsian, Rhythmbox and Strawberry.

[!TIP] iTunes on Windows does not provide a practical way to bulk export playlists.<br> TuneLift is a Windows-only companion tool that exports all iTunes playlists to standard .m3u files for use with ListPorter.

🧰 Features

💻 Runs on Windows 10 & 11, Linux (x64, ARM64, ARM32) and macOS (Intel & Apple Silicon).
📂 Imports standard or extended M3U audio playlists to Plex.
🌐 Works with any Plex server platform (Windows, Linux, NAS, macOS) via the Plex API.
⏳ Triggers a Plex library update/scan before import to include new tracks.
✅ Skips importing playlists that haven’t changed.
🪞 Mirrors Plex playlists to match imported M3U files.
🎯 Fuzzy matching logic (using last three path parts) to improve playlist-to-Plex matching.
🔁 Force playlist paths to use / or \ to match your Plex server’s file format.
🛠️ Rewrite playlist paths using find & replace rules to match your Plex library.
🧭 Prepend a base path to support relative paths in playlists.
🧹 Deletes all Plex playlists before import.
🔗 Preserves playlist IDs to maintain compatibility with external players (e.g. Sonos)
📘 Logs activity to timestamped text files.

📦 Download

Get the latest version from https://github.com/mrsilver76/listporter/releases.

Each release includes the following files (x.x.x denotes the version number):

|Platform|Download| |:--------|:-----------| |Microsoft Windows 10 & 11|ListPorter-x.x.x-win-x64.exe ✅ Most users should choose this| |Linux (64-bit Intel/AMD)|ListPorter-x.x.x-linux-x64| |Linux (64-bit ARM), e.g. Pi 4 and newer|ListPorter-x.x.x-linux-arm64| |Linux (32-bit ARM), e.g. Pi 3 and older|ListPorter-x.x.x-linux-arm| |Synology DSM|ListPorter-x.x.x-linux-x64 🐳 Run via Docker / Container Manager| |macOS (Apple Silicon)|ListPorter-x.x.x-osx-arm64| |macOS (Intel)|ListPorter-x.x.x-osx-x64| |Other/Developers|Source code (zip / tar.gz)|

[!TIP] There is no installer for native platforms. Just download the appropriate file and run it from the command line. If you're using Docker (e.g. on Synology), setup will differ - see notes below.

macOS users

Download the appropriate binary for your platform (see table above).
Install the .NET 8.0 runtime. Slightly more technical information can be found here.
⚠️ Do not install the SDK, ASP.NET Core Runtime, or Desktop Runtime.
Make the downloaded file executable: chmod +x ListPorter-x.x.x-<your-platform>
If you get zsh: killed when running the executable then:
- Apply an ad-hoc code signature: codesign --force --deep --sign - ListPorter-x.x.x-<your-platform>
- Remove the quarantine attribute: xattr -d com.apple.quarantine ListPorter-x.x.x-<your-platform>

Linux users

Download the appropriate binary for your platform (see table above).
Install the .NET 8.0 runtime. Slightly more technical pages can be found here.
⚠️ Do not install the SDK, ASP.NET Core Runtime, or Desktop Runtime.
Make the downloaded file executable: chmod +x ListPorter-x.x.x-<your-platform>

Synology DSM users

Only Plus-series models (e.g. DS918+, DS920+) support Docker/Container Manager. Value and J-series models cannot run ListPorter this way.
For DSM 7.2+, use Container Manager; older versions use the Docker package.
Install the .NET 8.0 Linux runtime inside the container or use a .NET container image.
⚠️ Do not install the SDK, ASP.NET Core Runtime, or Desktop Runtime.
Use the ListPorter-x.x.x-linux-x64 binary inside the container.
Mount your playlist folder into the container with read access and ensure network access to Plex.

Platform testing notes

Tested extensively: Windows 11
Tested moderately: Linux (64-bit ARM, Raspberry Pi 5 only)
Not tested: Windows 10, Linux (x64), Linux (32-bit ARM), Synology DSM (via Container Manager), macOS (x64 & Apple Silicon)

[!NOTE] Docker, Synology DSM, and macOS environments have not been tested, and no platform-specific guidance is available as these setups are outside the developer’s experience. While ListPorter should work fine on them, support will be limited to questions directly related to the tool itself.

🚀 Quick start guide

This is the simplest and most common way to use ListPorter. It works across platforms, refreshes the library before starting and uses fuzzy matching to automatically align playlist paths with your Plex library.

[!TIP] To ensure Plex contains only the playlists in your import folder (i.e. remove any that aren’t there), add the --mirror (-m) option.

ListPorter -s 127.0.0.1 -t ABCDEFG -l 8 -i "C:\Playlists" -k

ListPorter --server 127.0.0.1 --token ABCDEFG --library 8 --import "C:\Playlists" --update

The example below shows a more advanced scenario suitable when fuzzy matching isn’t enough. It demonstrates how to explicitly rewrite paths and convert formats when importing playlists created on one platform (e.g. Windows) into a Plex server running on another (e.g. Linux). Note that --find (-f) uses forward slashes because --linux (-l) converts backslashes to forward slashes.

[!CAUTION] This example deletes existing Plex playlists before import. Only use --delete (-d) if you're sure you want to replace everything..

ListPorter -s pimachine -t ABCDEFG -l 10 -i "C:\Playlists" -x -l -f "C:/Users/MrSilver/Music/iTunes/iTunes Media/Music" -r "/home/pi/music" -d

ListPorter --server pimachine --token ABCDEFG --library 10 --import "C:\Playlists" --exact-only --linux --find "C:/Users/MrSilver/Music/iTunes/iTunes Media/Music" --replace "/home/pi/music" --delete

💻 Command line options

ListPorter is a command-line tool. Run it from a terminal or command prompt, supplying all options and arguments directly on the command line. Logs with detailed information are also written and you can find the log file location using --help (-h).

ListPorter -s <address>[:<port>] -t <token> -l <library> -i <path> [options]

Mandatory arguments

-s <address>[:<port>], --server <address>[:<port>]
Plex server address, optionally including the port (e.g. localhost:32400). If you do not supply a port then the default (32400) will be used.

You can also prefix with https:// or http:// to specify the connection type (default is http).

[!NOTE] If Plex is configured to require secure connections (under Settings > Remote Access) then plain http:// connections will fail, so use https:// instead.

-t <token>, --token <token>
Plex authentication token. Required to interact with your Plex server. To find out your token, see Plex's guide.

[!NOTE] If you want to upload playlists for a specific Plex Home user, you must use the access token associated with that user, not the admin account. Refer to this FAQ entry for detailed steps on obtaining a Plex Home user token.

[!CAUTION] You should never share your Plex token with anyone!

-l <library>, --library <library>
Plex library ID that contains your music. This must be a Music library. To find your library ID, go into the Plex web client, hover the mouse over the library you want and look at the URL. It will end with source=xx where xx is the library ID.
-i <path>, --import <path>
Path to a single .m3u file or a directory containing multiple .m3u files.

Optional arguments

Playlist sync options

These options will remove playlists from your Plex server under specific conditions. Only playlists that are manual (not smart/dynamic), contain audio tracks only and belong entirely to the music library specified by --library will ever be deleted. No other content (such as music files, metadata or non-matching playlists) is modified or removed..

-d, --delete
Deletes all existing playlists in the specified Plex music library before importing any new ones.
-m, --mirror
Mirrors Plex playlists to

Listporter

Install / Use

README