Docker Compose Plex

May 5th 2024

Do not run this docker-compose.yaml without configuring it!

The docker compose example below creates a Docker container using the official Plex docker image and the latest tag. Many options are commented to describe what they do and possibly change functionality. Please read through them before using the file. No security information is stored in file below. Make sure the paths in ‘volume’ section exist in the host!

Save the file below as docker-compose.yaml and then run it using the command docker compose up. Click here for a guide on Docker

    image: plexinc/pms-docker:latest # Set specific: plexinc/pms-docker:
    container_name: plex
    network_mode: host # Change this to 'bridge' to define ports, example ports below
      #- 32400:32400/tcp
      #- 8324:8324/tcp
      #- 32469:32469/tcp
      #- 1900:1900/udp
      #- 32410:32410/udp
      #- 32412:32412/udp
      #- 32413:32413/udp
      #- 32414:32414/udp
    # Uncomment the devices section for tv tuners and intel gpus
      #- /dev/dvb:/dev/dvb # Uncomment this device for typical USB TV Tuner cards
      #- /dev/dri:/dev/dri # Uncomment this to use intel GPUs for Hardware Transcoding
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York # Change this to match your server's timezone
      #- PLEX_CLAIM= # Uncomment this to setup Plex server, get your claim code from here -
      # Uncomment the lines below to use Nvidia GPUs for Hardware Transcoding
      - /etc/localtime:/etc/localtime:ro # Sync the container's time to the host's time
      - ./plexmediaserver:/config # Plex server application data is stored in a folder called 'plexmediaserver' in the same directory as the docker-compose.yaml file
      # Uncomment the lines below for each library, 
      # make sure the path on the left of the colon (:) exists on the host! `/mnt/tv`
      #- /mnt/tv:/mnt/tv
      #- /mnt/movies:/mnt/movies
      #- /mnt/music:/mnt/music
      #- /mnt/transcode:/mnt/transcode
    restart: unless-stopped
    # Uncomment the lines below to use Nvidia GPUs for Hardware Transcoding
    #  resources:
    #    reservations:
    #      devices:
    #        - driver: nvidia
    #          count: 1
    #          capabilities: [gpu]

Hardware Transcoding

To effectively use Nvidia hardware for Plex’s hardware acceleration follow the guide below.

Setup Nvidia GPU for Docker


PlexDBRepair is a tool for repairing and optimizing the Plex Media Server database. It is possible to use this tool with a containerized Plex Media Server instance but it requires some changes to the docker-compose.yaml file.

Install Inside Container

These are the steps to install PlexDBRepair inside the plex container. This is not a permanent install and could be removed if the container is brought down. This is useful if you need to use it to fix a current problem and the docker container is working. If you have a similar problem again, you might need to do these steps again to get the code back in the container.

Enter the plex container, in the command below plex is the container name as defined in the docker-compose.yaml from before.

docker exec -it plex bash

Change directory to somewhere you can work in, such as /opt/.

cd /opt/

In your browser, go to the URL
In the Assets section find the entry named Source code (tar.gz) and copy the link to it.

Back in the docker container, use the code below to download the archive. Make sure to replace the URL at the end of the command below with the URL you copied earlier.

curl -LJO

Extract the code from the archive. Make sure to replace the name of the archive at the end of the command!

tar xf PlexDBRepair-1.06.00.tar.gz

Enter the extracted archive directory

cd PlexDBRepair-1.06.00.tar.gz

Set the script’s permission to allow execution.

chmod +x

Run the script.


Install Outside Container

This method of installation is useful if you want to permanently keep the script installed. Some people run this script on a schedule to keep the DB healthy and check for any errors before they become problems. Though understand, automating the DB repair process could cause DB issues too, since no software is bug free. Regardless of the process, always ensure you have a backup of the DB.

Its also possible to download the code in such a way that you can use git to keep it updated.

Click here for a guide to install git

The config changes below assume you’re installing PlexDBRepair next to the docker-compose.yaml file for your Plex Media Server. Paths that start with ./ are relative to the docker-compose.yaml file.

Change the current working directory to the location of the docker-compose.yaml file for Plex Media Server. Here we assume that’s /opt/plex/.

cd /opt/plex

We can verify the files in this directory using ls. In the example below the contents of /opt/plex are docker-compose.yaml, PlexDBRepair, and plexmediaserver.

user@hostname:/opt/plex$ ls
docker-compose.yaml  PlexDBRepair  plexmediaserver

Download the repo using git.

git clone

Move into the repo’s directory

cd PlexDBRepair

Set the script’s permission to allow execution.

chmod +x

Find the Plex Media Server docker-compose.yaml file that’s running your instance of Plex.
You need to add the path of the PlexDBRepair directory on the host and map it to a directory in the container.

Open the file to modify it as shown below.

      - /etc/localtime:/etc/localtime:ro # Sync the container's time to the host's time
      - ./plexmediaserver:/config # Plex server application data is stored in a folder called 'plexmediaserver' in the same directory as the docker-compose.yaml file
      # Other volumes defined in your docker-compose.yaml go here
      - ./PlexDBRepair:/opt/PlexDBRepair  # Add this line to the bottom of your docker-compose.yaml's 'volumes' section

In the code above, ./PlexDBRepair means the PlexDBRepair folder is next to the docker-compose.yaml file for Plex Media Server. Within the container, the contents of the hosts’s PlexDBRepair directory will be visible at the path /opt/PlexDBRepair.

docker exec -it plex bash
root@plex:/# ls /opt/PlexDBRepair  DBRepair-Windows.bat  ReleaseNotes

Run the script

PlexDBRepair has a relatively simple text based interface. As of writing the current menu looks like the example below.


  1 - 'stop'      - Stop PMS.
  2 - 'automatic' - Check, Repair/Optimize, and Reindex Database in one step.
  3 - 'check'     - Perform integrity check of database.
  4 - 'vacuum'    - Remove empty space from database without optimizing.
  5 - 'repair'    - Repair/Optimize databases.
  6 - 'reindex'   - Rebuild database database indexes.
  7 - 'start'     - Start PMS

  8 - 'import'    - Import watch history from another database independent of Plex. (risky).
  9 - 'replace'   - Replace current databases with newest usable backup copy (interactive).
 10 - 'show'      - Show logfile.
 11 - 'status'    - Report status of PMS (run-state and databases).
 12 - 'undo'      - Undo last successful command.

 21 - 'prune'     - Prune (remove) old image files (jpeg,jpg,png) from PhotoTranscoder cache.
 42 - 'ignore'    - Ignore duplicate/constraint errors.

 88 - 'update'    - Check for updates.
 99 - 'quit'      - Quit immediately.  Keep all temporary files.
      'exit'      - Exit with cleanup options.

Enter command # -or- command name (4 char min) :

Up to date menu examples can be found here -

An up to date feature list can be found here -

Automatic mode is typically what most people will need to run. That is option 2 in the menu or auto. This will run the steps stop, check, repair, and reindex.

vacuum isn’t always necessary, but it can help clean up unnecessary usage of space by the database file. There are some performance benefits of doing this, but its not always necessary. If reindex doesn’t help improve performance of the database, try vacuum.

The VACUUM command is explained further here -

The REINDEX command is explained further here -

This post is written by Gouthaman Raveendran, licensed under CC BY-NC 4.0.