How to Prevent Plex from Changing Movie Posters

When Plex updates the metadata for movies on your server it may also change the movie poster to one it finds online. If you have carefully set your posters for your movies this can be frustrating to have Plex change the posters.

To prevent this from happening, there are a few things you can do in Plex to keep your own selected posters from being changed.

The next few sections will describe the methods you can use to keep your movie posters from being changed by Plex.

How to Prevent Plex from Changing Movie Posters

Storing and using your movie posters

The first method is simply to store the movie poster in the same folder as your movies, and then have Plex use that poster.

This works best when you each of your movies in its folder, that way it keeps things organized on your hard drive.

Poster naming conventions

To store posters in a folder containing a single movie, you would use the following poster naming convention:

Movies/MovieName (Release Date)/PosterName.ext

The PosterName value can be one of the following:

  • cover
  • default
  • folder
  • movie
  • poster

For example, for The Godfather, you would do something like the following:

    /The Godfather (1972)
        /The Godfather (1972).mkv

You can still store your posters even if all your movies are in a single folder.

The naming convention for movie posters stored in a single movies folder is as follows:

Moves/MovieName (Release Date).ext

For example, The Godfather (1972).jpg would be the name of a poster for The GodFather.

You can have multiple posters for a movie by appending a number after the file name, such as:



The Godfather (1972)-1.jpg

The first poster doesn't need a number appended, however, any additional posters should include a number.

If you have carefully set your movie posters and would like to download them, you can use the script documented in How to Download Movie Posters from Your Plex Server.

Enable local assets Plex movie agent

Once you have the poster files added to the same folder as your movie files, you will need to enable the movie library in Plex to use the local assets.

To do that, use the following steps:

  1. Log into your Plex server as an administrator, and then hover your mouse over the movie library you wish to edit, click the three dots, and then select the Manage Library->Edit... option.
    Plex Edit Movie Library Option.
    The Plex edit movie library option
  2. From the Edit Movies dialog, click the Advanced option on the left, then scroll down and click the Use local assets checkbox, and then click the Save Changes button.
    Enabling the Use Local Assets Option for a Movie Library
    Enabling the 'Use Local Assets' option for a movie library

After doing the above steps, Plex will now use the local posters for your movies instead of the ones it downloads from the Internet.

Locking the movie poster using the Plex API for a single movie

Sometimes the reason Plex may change movie posters is because the posters aren't "locked."

When you make changes to metadata for a media item in Plex, you will notice that a lock icon beside the field you change changes from a gray color to an orange color.

An orange lock means the field has been "locked" and indicates that Plex won't update that field when metadata for that media item is refreshed.

There is no lock indicator for movie posters in Plex, so you can't manually enable the lock on a poster.

You can use the Plex API to lock the poster by calling the Update Movie Details API command.

The steps to lock the movie poster using the Plex API are as follows:

  1. Call the Get Libraries API to find the key associated with the movie library.
  2. Get the key of the movie by calling the Get All Movies API command.
  3. With both the movie library key and the movie key, you can lock the movie poster for the movie using the following command:
    curl -X PUT http://{ip_address]:32400/library/sections/{library_key}/all?type=1&id={movie_key}&thumb.locked=1&X-Plex-Token={plex_token}
    import requests
    plex_url = http://{ip_address}:32400/library/sections/{library_key}/all?type=1&id={movie_key}&thumb.locked=1&X-Plex-Token={plex_token}
    response = requests.put(plex_url)
    $response = Invoke-RestMethod 'http://{ip_address}:32400/library/sections/{library_key}/all?type=1&id={movie_key}&thumb.locked=1&X-Plex-Token={plex_token}' -Method 'PUT'
    Write-Output $response

Locking all movie posters using the API

You can easily lock the posters for all movies on your Plex server with a simple script.

The Python script below will lock the posters for all movies on a Plex server:

import os
import requests
import xml.etree.ElementTree as ET

plex_url = os.environ.get('PLEX_URL')
plex_token = os.environ.get('PLEX_TOKEN')
library = {library_id}

def get_all_media():
    Gets all media for a library.

    Keyword arguments:
    id -- the id of the library
    response = requests.get('{0}/library/sections/{1}/all?X-Plex-Token={2}'.format(plex_url, library, plex_token))
    if response.ok:
        root = ET.fromstring(response.content)
        return root
        return None

def get_movie_key(video_tag):
    Gets the key associated with the video.

    Keyword arguments:
    video_tag -- the video tag returned by the Plex API
    key = video_tag.get('ratingKey')
    if key:
        return key
        return None

def lock_poster(movie_key):
    Locks the movie's posters so it can't be changed by Plex.

    Keyword arguments:
    movie_key -- the key associated with the movie
    response = requests.put('{0}/library/sections/{1}/all?type=1&id={2}&thumb.locked=1&X-Plex-Token={3}'.format(plex_url, library, movie_key, plex_token))
    if response.status_code != 200:
        print("Couldn't lock the poster. Status code: {0}".format(response.status_code))

root = get_all_media()
for video_tag in root.findall('Video'):    
    movie_key = get_movie_key(video_tag)
    if not movie_key:
        print('The key associated with the movie was not found.')


How to use the script

To use the script, you will need to do the following:

  1. Install Python.
  2. After Python is installed, run the following pip command to install the dependencies:
    pip install requests
  3. Copy the above script and save it as a Python file, for example:
  4. Edit the script to replace {library_id} with the movies library ID from your Plex server.
  5. Create an environment variable called PLEX_URL and set it to the URL of your Plex server. For example: http://localhost:32400.
  6. Create an environment variable called PLEX_TOKEN and set it to your Plex token.

What does the script do?

The above script will make multiple calls to the Plex API to perform the following steps:

  1. It gets all the movie files by calling the Get All Movies API command. This is done in the get_all_media function.
  2. Once all the movies have been retrieved, it will loop through all the movies and then call the get_movie_key function to get the key for each movie in the library.
  3. Next, the lock_poster function is called to lock the poster for the movie. This URL is the Update a Movie endpoint.

Using Plex Meta Manager

Another method of preventing Plex from changing your movie posters is to setup and use Plex Meta Manager

Plex Meta Manager is a popular tool for managing metadata for your media libraries, including managing posters. You can even display overlays over your posters that can display specific information about the movie.

I don't currently use this tool, but I have heard good things about it, so may check it out someday.

At this time, though, I like to keep my Plex installation simple to prevent me from having to perform too much maintenance on it.

The above sections provided different methods of preventing Plex from changing the movie posters that you have set up yourself. If you have carefully curated your posters, you can try one of the methods to protect the time you have spent to make Plex the way you want.

Photo of Paul Salmon
Started managing a Plex server in November 2014 and has been sharing his experience and what he has learned on Plexopedia. He is exploring and documenting the Plex API to help automate tasks for Plex to reduce the management effort of his server.

Dialogue & Discussion