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.
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, automatically finds the (single) music library, 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 -i "C:\Playlists" -k

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

The example below shows a more advanced scenario suitable when you have more than one music library (ID 10) and 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.

  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!

• -i <path>, --import <path>
  Path to a single .m3u or .m3u8 file, or a directory containing playlist files to import.

Library options

• -l <library>, --library <library>
  Optional Plex music library ID. If your Plex server has only one Music library, ListPorter will automatically detect and use it, so this option is not required. If your server has multiple music libraries, ListPorter will list each library with its ID and name and ask you to change your command line to specify which one to use.

Playlist sync options

These options will remove playlists from your Plex server under specific conditions.

Only playlists meeting all of the following criteria will ever be deleted

• The playlist is manual, not smart/dynamic.
• The playlist contains audio tracks only.
• The playlist belongs entirely to the selected music library.

The selected library is either the library specified with --library or, when this is not supplied, the single music library automatically detected by ListPorter.

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 match the imported .m3u files. Any Plex playlists not represented in the imported list will be removed.

Caution

Be careful when using --mirror with a single file: this will cause all other playlists in the library to be removed, keeping only the one you provided.

Path rewriting options

ListPorter tries to match each file path in your playlist with the paths Plex has stored. It first attempts an exact match. If that fails, it automatically uses fuzzy matching, based on the assumption that music files are organised with a structure of artist/album/track or artist\album\track. It compares only the last three parts of each path, ignoring drive letters, shares, or deeper folder structures.

This approach works well when root paths differ or when file systems vary across devices, as long as the layout near the file itself is consistent. However, if files have been renamed or stored with a different folder hierarchy, exact or fuzzy matching may fail.

Fuzzy matching is automatically disabled when using -f (--find) or -b (--base-path), as these options explicitly rewrite how paths are interpreted. Other options, including -w (--windows) and -u (--unix) do not disable fuzzy matching because separator differences between Windows and Unix are handled automatically.

These options don’t modify the playlist files themselves - they only affect how paths are interpreted during import.

• -u, --unix, --linux
  Force playlist paths to use forward slashes (/), often required for Plex servers running on Linux, macOS, or NAS. This does not affect any path set using --base-path.

• -w, --windows
  Force playlist paths to use backslashes (\), as used by Plex servers on Windows. This does not affect any path set using --base-path.

• -f <text>, --find <text>
  Searches for a substring in each song's file path. Intended for use with --replace to rewrite paths. Matching is case-insensitive and only one --find string is supported per run. Paths set using --base-path will not be searched.

Important

If you're also using --unix or --windows, the slash conversion happens before the search-and-replace step. Be sure your --find value uses the correct slash style for matching.

• -r <text>, --replace <text>
  Replaces matched text from --find with this new value. If --find is used and there is no --replace value, then it will be assumed to be blank and the matching string will be removed. Paths set using --base-path will not be affected.

• -b <path>, --base-path <path>
  Specifies a base path to prepend to all playlist entries. This is useful when your .m3u playlists contain relative paths (e.g. ./music/track.mp3). If a track’s path starts with ./ or .\ then the leading dot will be removed before applying the base path.

  The base path is applied after all other rewriting options (such as --find/--replace or --unix/--windows) and will affect all playlists in the current run.

• -x, --exact-only
  Disables fuzzy matching and any automatic path adjustments. Only exact, case-insensitive matches will be used to link playlist files to Plex tracks. Use this if you want full control and are relying entirely on exact paths or other file rewriting options listed above.

Other options

• -k, --update
  Instructs Plex to update or scan the specified library before ListPorter starts importing playlists. This ensures any new songs you’ve added to your Plex library are recognized and indexed before importing. Without this, your playlists might reference new tracks Plex hasn’t scanned yet, which can cause errors during import.

Note

• ListPorter waits for the Plex library scan to finish before importing playlists. The time this takes depends on your library size and number of changes. There will also be a short 5-10 second delay between Plex finishing the scan and ListPorter continuing.
• Non-admin (Plex Home) users cannot trigger a library scan. This is a restriction enforced by Plex, not ListPorter.

• -nc, --no-check
  Disables GitHub version checks for GroupMachine.

  Version checks occur at most once every 7 days. ListPorter connects only to this URL to retrieve version information. No data about you, your music library or your Plex server is shared with the author or GitHub - you can verify this yourself by reviewing GitHubVersionChecker.cs

• -v, --verbose
  Outputs additional information to the log files to aid in debugging.

• /?, -h, --help
  Displays the full help text with all available options, credits and the location of the log files.

🧩 How playlists are matched on Plex

The program will only recognise and process playlists on your Plex server that meet all of the following criteria:

1. All items in the playlist must be audio - playlists containing video or mixed content are ignored.
2. The playlist is manual, not a smart/dynamic playlist.
3. All audio tracks in the playlist belong to the selected music library.

These rules apply to all playlist-related operations, including --mirror and --delete.

Note

The program will only report the number of playlists that meet these criteria, not the total number of playlists on your Plex server. If a playlist doesn’t appear or isn’t deleted/modified as expected, it likely does not meet one or more of these conditions.

❓ Frequently Asked Questions

Getting started and running the tool

• I'm struggling to understand how to run or configure ListPorter. What should I do?
• Can I just double-click on this program from Windows Explorer and it run?
• Can I run this on a headless Linux server or NAS?

Configuration and command line options

• Can I import playlists directly to a specific Plex Home user instead of the main/admin account?
• What does the --mirror option do exactly?
• I'm using --windows or --unix. Why isn't --find matching?

Logging and debugging

• Where are the logs stored? What do they show?
• I'm getting an error about fuzzy maching conflicts
• Why do I see a warning that some items failed to match the Plex database?
• Why am I being asked to pick a music library?

Plex interaction and playlist behavior

• Does this overwrite existing playlists in Plex?
• Why does the tool clear the contents of existing playlists instead of deleting and recreating them?

🛟 Questions/problems?

Please raise an issue at https://github.com/mrsilver76/listporter/issues.

💡 Future development: open but unplanned

ListPorter currently meets the needs it was designed for, and no major new features are planned at this time. However, the project remains open to community suggestions and improvements. If you have ideas or see ways to enhance the tool, please feel free to submit a feature request.

📝 Attribution

• Plex is a registered trademark of Plex, Inc. This tool is not affiliated with or endorsed by Plex, Inc.
• Music & multimedia icon by paonkz - Flaticon (https://www.flaticon.com/free-icons/music-and-multimedia)
• With thanks to https://www.plexopedia.com/plex-media-server/api/ for Plex API documentation.

🕰️ Version history

See CHANGELOG.md