Introduction

Plex Linter is a python script that looks for various potential issues in your library, such as

• Duplicate album titles (for albums that have been incorrectly split)
• Duplicate artists (for artists that have been split)
• Tracks without titles (sometimes Plex metadata deletes track titles)
• Tracks linked to artists with Plex metadata that differ from what the MP3 tags say (requires running on the plex server and using the --local flag)
  • Note that the linter only works for music libraries currently

Setup

Requirements

1. Python 3.13
2. Poetry

Note: Steps below are for OSX (other operating systems will require tweaking to the steps)

1. Install uv according to the instructions

2. Clone the plex_linter repo

   git clone https://github.com/karloskalcium/plex_linter

3. Install the dependencies

   cd plex_linter
   make install

Usage

1. Start the plex_linter, it will check for a config file, create a new one if it doesn't exist, and ask you to fill your Plex server URL and credentials to generate a Plex Access Token

   uv run plex_linter
   

2. If you are running on the plex server and want to check for mismatched tags, pass the --local flag as follows:

   uv run plex_linter --local
   

Configuration

Sample

# plex_linter.toml
[server]
server_url = "http://plex.your-server.com"
server_token = "{your-X-Plex-Token}"

[content]
libraries = [
    "Music",
    "Audiobooks"
]

Plex

Plex Libraries

1. Go to Plex and get all the names of your Plex Music Libraries you want to run the linter on

   • Example Library:

     

2. Under libraries, type in the Plex Library Name (exactly)

3. Note that the linter only works for music libraries currently

Plex Server URL

• Your Plex server's URL
  • This can be any format (e.g. http://localhost:32400, https://plex.domain.ltd)

Plex Token

1. Obtain a Plex Access Token:

   • Fill in the Plex URL and Plex login credentials, at the prompt, on first run. This only occurs when there is no valid plex_linter.toml present.

     or

   • Visit https://support.plex.tv/hc/en-us/articles/204059436-Finding-an-authentication-token-X-Plex-Token

---

Inspiration

This project started as a fork of https://github.com/l3uddz/plex_dupefinder and used a lot of that code as a starting point.