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, 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 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.

If you use any of the options below to rewrite paths, fuzzy matching will be automatically disabled. This is to avoid conflicts between automated and manual path handling.

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.

Note

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 library ID provided via --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?

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

1.1.1 (06 October 2025)

• Output now confirms which Plex account or managed user the playlists will be uploaded to, based on the token provided.
• Fixed bug where logs were not being saved in the correct location.
• Fixed bug where Plex token was being incorrectly saved in the logs.

1.1.0 (24 September 2025)

• Added -k (--update) to force Plex to scan the library prior to importing.
• Logger now includes OS information to help with troubleshooting across platforms.
• All fuzzy match clashes during the database build are now logged, not just the first.
• When fuzzy match clashes occur, ListPorter now exits with an error and a link to the FAQ.
• Supplying an invalid Plex library ID now returns a clear error, instead of crashing.
• .m3u track paths incorrectly prefixed with file:// or file-relative:// are now cleaned automatically.
• Legacy log folders named "Plex Playlist Uploader" and "PlexPU" are no longer deleted.
• Added -nc (--no-check) to disable GitHub version checking.
• Added header displaying key settings and command line options used.
• Updated GitHub version checking code and publish Powershell script.
• Cleaned up various pieces of code (analyzer suggestions regarding naming, simplifications, and style)
• FAQs have been moved to a separate page to reduce clutter in the main README.

1.0.0 (27 June 2025)

• 🏁 Declared as the first stable release.
• Added fuzzy matching logic to improve playlist-to-Plex track matching when exact paths don’t align.
• Added support for secure connections (HTTPS) when communicating with Plex servers.
• Added --base-path (-b) option to prepend a base path for playlists using relative paths.
• Added --linux as an alias for --unix.
• Improved --help formatting for better readability on 80-character terminals.
• Added contextual tips for import errors to assist troubleshooting without needing logs.
• Reduced API page size to 1000 to prevent Plex from generating warning entries.
• Path matching and rewriting issues are now surfaced to users (max 5 per playlist).
• Replaced Publish.bat with a streamlined Publish.ps1 script for building executables.
• Added linux-arm builds for compatibility with Raspberry Pi 3 devices.
• Added additional logging to aid in debugging.
• Added statistics showing playlists skipped, created, updated and deleted.
• Fixed bug where a folder with no m3u or m3u8 files would not generate an appropriate error.
• Made output less spammy whilst loading and parsing m3u files.
• Added GNU GPL v2 license notice to source files for clarity.

0.9.3 (24 May 2025)

• Fixed version checker incorrectly reporting updates available when already on the latest version.

0.9.2 (24 May 2025)

• Updated track discovery to use a more comprehensive Plex API endpoint, resolving issues where some valid items (like orphaned tracks) were previously omitted. Thanks to u/AnalogWalrus and u/spikeygg for spotting and helping to debug.
• Improved performance by over 30% through fewer API calls and reduced track lookups during playlist processing.
• Added hostname and port number of Plex server during connection test.
• Cleaned up version number handling, ensuring consistency and correct handling of pre-releases.
• Improved verbose mode to help in debugging issues.
• Added details about --verbose to --help.
• Cleaned up various pieces of code.

0.9.1 (19 May 2025)

• Renamed to "ListPorter" to avoid any potential issue with the Plex legal team.
• Fixed bug that meant that the Plex token and machine ID could end up in the logs.
• Log folders generated by 0.9.0 are removed, as they can contain token data.
• Tracks marked as deleted (but not removed) are now considered for playlists.
• Fixed logs to report more useful information.
• Fixed copyright and minor number formatting.
• Added error catching for some file operations.
• Changed incorrect scary messaging when there are empty playlists.
• Fixed terrible error messages when unable to connect to Plex server.
• Added links to Plex support articles for common connection issues.
• Added 10 second notification to avoid people thinking that the program had locked up.
• Updated Publish.bat to include missing osx-x64 (macOS on Intel) build.

0.9.0 (16 May 2025)

• Initial release, a C# port from iTunes Playlist Exporter.
• Now cross-platform, with support for Windows, Linux (x64 and ARM) and macOS.
• Removed iTunes exporting functionality, now handled by a separate tool called TuneLift.
• Added automatic version checking with update notifications.
• Playlists are only updated if they have changed, eliminating the need to delete and re-import everything.
• Added --mirror option to remove playlists from Plex that no longer exist in the input directory.
• Modified playlists retain their original playlist ID, so external players like Sonos can continue to reference them.