How To Run Plex Media Server in Docker and Docker Compose

Plex Media Server in Docker answers on port 32400 about 4 seconds after docker compose up. It is not usable until its agent plug-ins finish loading, though, and on our test box that took 75 seconds on a clean first boot and once stalled for 11 minutes. After that one-time cost the container idles at 87 MiB of RAM and comes back in 11 seconds on a restart. Those numbers decide how you size the host and how long you wait before you open the web app.

Original content from computingforgeeks.com - post 115485

Below, Plex runs under Docker Compose on Ubuntu using the plexinc/pms-docker image that Plex itself publishes, with host networking, persistent volumes and a claim step that works on a headless server. We measured it against the LinuxServer.io image on the same VM, covered the bridge-mode port list and the Intel Quick Sync device block, and logged every error we hit on the way. Ubuntu 24.04 uses the same Docker repository and the same steps, but only 26.04 was run.

Benchmarked October 2026 on Plex Media Server 1.43.4 (Ubuntu 26.04).

Plex Media Server Docker results

Our test box was a Proxmox VM with 2 vCPUs (host CPU type), 4 GB of RAM and a 40 GB disk, running Docker Engine from the Docker apt repository. Every figure below comes from the lab logs of that VM, with the official image unless the row says otherwise.

Metric	Official plexinc/pms-docker	LinuxServer.io plex
Image on disk (compressed download)	541 MB (163 MB)	638 MB (188 MB)
Pull time on the lab link	22.9 s	33.6 s
First boot, /identity answers	4.4 s	4.4 s
First boot, plug-ins finished loading	74.6 s (one run: 11.5 min)	74.5 s
Idle RAM right after first boot	235.6 MiB	244.4 MiB
Idle RAM after a restart	86.5 MiB	not measured
Restart to fully ready	10.9 s	not measured
Scan of 2 movies and 3 episodes (41 MB)	3.8 s	not measured

Both images run the same Plex build, so the server itself behaves the same, and first boot times matched to a tenth of a second. The difference sits in the wrapper. The official image is 97 MB smaller on disk and pulled 11 seconds faster, and it is the one Plex documents and supports, so it is the image this guide uses. The LinuxServer.io image is the better pick only if you already run other LinuxServer.io containers and want the same PUID/PGID conventions and init scripts across all of them.

The size gap is visible straight from docker images on the test box:

Docker adds a layer between Plex and the hardware, and on a box that runs nothing else that layer buys little. A dedicated Plex machine is simpler with the native Plex package for Ubuntu, while Docker pays off on a shared home server where Plex sits next to other containers and you want one upgrade and backup routine for all of them.

The memory rows need a careful read. Right after the first boot, Plex starts every legacy metadata agent as its own Python “Plex Script Host” process, seven of them on our box, which is why the container sat at 235 MiB. After one restart only two of those processes came back and the container settled at 86.5 MiB with 55 PIDs. If you size a small NAS or a mini PC from the first-boot figure, you overestimate the steady state by almost three times. Here is how each number was taken:

• Image size: the DISK USAGE and CONTENT SIZE columns of docker images right after the pull, with no other images on the host.
• Ready times: a loop polling http://127.0.0.1:32400/identity every 0.5 seconds. “Plug-ins finished” is the moment the startState attribute disappeared from that reply.
• Idle RAM: docker stats --no-stream, three samples 30 seconds apart, taken 3 to 4 minutes after the server reported ready, with no client connected.
• Library scan: time from creating both libraries until the API listed all five items, on files generated with the ffmpeg testsrc2 and smptebars sources.

Transcoding was not measured. A transcode benchmark needs real client sessions and, for hardware transcoding, a Plex Pass account and a GPU, and the lab had neither.

Prerequisites

Plex itself is light: the numbers above show under 100 MiB of RAM at idle. What sizes the host is the library and the transcoder, so start from those rather than from our lab spec:

• Disk for /config: the database and artwork cache. The Plex Docker README puts it at a few GB for most libraries and hundreds of GB when preview thumbnails are enabled for a large collection. Ours held 8.7 MB after the first scan of five files.
• Disk for /config needs file locking: keep it on local storage. Plex warns that NFS and SMB shares usually lack the locking SQLite needs, which corrupts the database over time.
• CPU or GPU for transcoding: direct play costs almost nothing, while each software transcode of a 1080p stream can take most of a modern core. An Intel CPU with Quick Sync moves that load to the iGPU (Step 7).
• Disk for /transcode: temporary segments, which Plex says can reach tens of GB during heavy transcoding.
• An Ubuntu 26.04 or 24.04 host with sudo access and outbound internet, plus a free Plex account for the claim step.

Our 2 vCPU, 4 GB VM is a floor for following along, not a recommendation for a household library. If you are still choosing the box that will hold the media, our roundup of the best NAS for Plex and self-hosting compares the units that can run this container next to the disks.

Step 1: Install Docker Engine and the Compose plugin

Ubuntu ships a docker.io package that works, but the Docker repository ships the current Engine and the docker compose plugin together, and it already publishes a resolute suite for 26.04. Add the Docker signing key first.

sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

Put the repository definition into a deb822 .sources file. The command fills in your Ubuntu codename and CPU architecture, so the same line works on 26.04 and 24.04:

printf "Types: deb\nURIs: https://download.docker.com/linux/ubuntu\nSuites: %s\nComponents: stable\nArchitectures: %s\nSigned-By: /etc/apt/keyrings/docker.asc\n" "$(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")" "$(dpkg --print-architecture)" | sudo tee /etc/apt/sources.list.d/docker.sources

Install the Engine, the CLI and the Compose plugin. On the test box the package install took 28 seconds.

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Add your user to the docker group so the rest of the guide runs without sudo. Skipping this means every later docker command fails with a permission error on /var/run/docker.sock, because only root and members of that group can open the socket. Pick up the new group in the current shell, or log in again:

sudo usermod -aG docker "${USER}"
newgrp docker

Confirm both tools and the service before you go further.

docker --version
docker compose version
systemctl is-active docker

On the test box the three checks printed the following, and any current Engine with Compose v2 or newer handles the file in Step 4.

Docker version 29.9.1, build dfc520d
Docker Compose version v5.6.0
active

The Docker CE install guide covers rootless mode, the log driver and the daemon settings in more depth, and the Docker Compose walkthrough explains the plugin if you have only used the old docker-compose binary.

Step 2: Create the Plex directories

Plex needs three host paths: /config for the database, /transcode for temporary segments and /data for the media. Set the root once and a time zone for the container, because both values are reused in the Compose environment file. Replace Africa/Nairobi with your own zone (timedatectl prints it):

export PLEX_ROOT="/srv/plex"
export TZ="Africa/Nairobi"

Create the tree and give it to your own user. The UID and GID that own these folders are the ones the container will run Plex as in Step 4, so files Plex writes stay readable from the host:

sudo mkdir -p "${PLEX_ROOT}"/{config,transcode,media/movies,media/tv}
sudo chown -R "$(id -u)":"$(id -g)" "${PLEX_ROOT}"

Plex matches files against online metadata by name, so the folder layout matters more than the location. Movies go in media/movies/Title (Year)/Title (Year).mkv and episodes in media/tv/Show Name/Season 01/Show Name - S01E01.mkv. Our test show was called “Lab Show”, and the TV agent matched it to an existing series titled “The Lab”, which is what an ambiguous name does. Use the real title and year and the match is usually right the first time; a wrong one is fixed later with Fix Match in the web app.

Step 3: Choose host or bridge networking

The Plex documentation offers three network modes, and the choice changes how much configuration you carry. Host networking is the one we recommend for a single Plex server:

• Host: the container shares the network stack of the host. Discovery, DLNA and remote access work the same as a native install, no ports need publishing, and the host firewall applies to every port (Step 5). Use this unless another service already holds port 32400 or 1900 on the host, such as a Jellyfin server with DLNA enabled.
• Bridge: the Docker default. Every port must be published, Plex needs ADVERTISE_IP to tell clients the host address, and it cannot set up port forwarding on your router because it sits behind two NAT layers. Use it when policy forbids host networking.
• Macvlan: the container gets its own address on the LAN. It behaves like host mode with a separate IP, at the cost of creating a macvlan network first. Useful when the host already runs another media server.

Steps 4 to 6 use host networking. The bridge version of the Compose file, which we also ran, is in Step 6.

Step 4: Write the Plex Docker Compose file

Keep the Compose project in its own directory. The variables in the file are filled from an .env file next to it, so the YAML stays the same on every host and only .env changes. The same layout imports cleanly into a web stack manager such as Dockge later, if you want to manage the stack from a browser:

mkdir -p ~/plex
vim ~/plex/compose.yaml

Paste this file. It is the exact file the test server ran:

services:
  plex:
    container_name: plex
    image: plexinc/pms-docker:latest
    restart: unless-stopped
    network_mode: host
    environment:
      - TZ=${TZ}
      - PLEX_CLAIM=${PLEX_CLAIM}
      - PLEX_UID=${PLEX_UID}
      - PLEX_GID=${PLEX_GID}
    volumes:
      - ${PLEX_ROOT}/config:/config
      - ${PLEX_ROOT}/transcode:/transcode
      - ${PLEX_ROOT}/media:/data

There is no version: line on purpose. The template Plex ships still starts with version: '2', and current Compose prints the attribute `version` is obsolete, it will be ignored, please remove it to avoid potential confusion on every command when it sees one. The restart: unless-stopped policy replaces the systemd unit older guides wrote for the container: after a reboot of the VM, Plex answered on 32400 about 15 seconds after the kernel started, with no unit file involved.

Now write the environment file from the variables set in Step 2. PLEX_UID and PLEX_GID come from your own account, and PLEX_CLAIM stays empty for now:

printf "TZ=%s\nPLEX_CLAIM=\nPLEX_UID=%s\nPLEX_GID=%s\nPLEX_ROOT=%s\n" "${TZ}" "$(id -u)" "$(id -g)" "${PLEX_ROOT}" > ~/plex/.env

Check what Compose will actually run before starting anything. A missing variable shows up here as an empty value rather than as a failed container:

cd ~/plex
docker compose config

In the rendered file, look for your time zone, both IDs and three bind mounts under /srv/plex.

name: plex
services:
  plex:
    restart: unless-stopped
    container_name: plex
    environment:
      PLEX_CLAIM: ""
      PLEX_GID: "1000"
      PLEX_UID: "1000"
      TZ: Africa/Nairobi
    image: plexinc/pms-docker:latest
    network_mode: host
    volumes:
      - type: bind
        source: /srv/plex/config
        target: /config
        bind: {}
      - type: bind
        source: /srv/plex/transcode
        target: /transcode
        bind: {}
      - type: bind
        source: /srv/plex/media
        target: /data
        bind: {}

Decide on PLEX_CLAIM before the first start. A claim token from plex.tv/claim signs the server into your account on its first run. The token expires about 4 minutes after it is issued, so a slow pull can eat the whole window. The image tries the exchange on every newly created container whose Preferences.xml holds no server token yet, which means a late token is not fatal. We leave it empty and claim through an SSH tunnel in Step 5, which has no time limit. If you prefer the token, paste it after PLEX_CLAIM= in ~/plex/.env and run Step 5 within those 4 minutes.

If it expired, put a fresh one in .env and run docker compose up -d again: Compose recreates the container because the environment changed, and docker logs plex prints Attempting to obtain server token from claim token followed by Token obtained successfully when the claim works. We checked the recreate and the attempt line with a deliberately invalid token, which produced no success line; a real token was not used.

Step 5: Start Plex and claim the server

Start the container in the background from the project directory.

docker compose up -d

Compose creates and starts one container.

 Container plex Creating
 Container plex Created
 Container plex Starting
 Container plex Started

The health check reports healthy within about 8 seconds, but that only means the HTTP listener is up. The /identity endpoint tells you whether the server finished starting, so poll it rather than the health status:

curl -s http://127.0.0.1:32400/identity

A finished server returns a single MediaContainer element with its version and claimed="0" until you sign it in. While plug-ins are still loading, the same element carries startState="startingPlugins"; wait until that attribute is gone:

<?xml version="1.0" encoding="UTF-8"?>
<MediaContainer size="0" apiVersion="1.2.3" claimed="0" machineIdentifier="372aa0f55e7171db589e76dfd68e28357563aa1c" version="1.43.4.10903-e5521bd8c">
</MediaContainer>

Here are the same checks in one terminal, including the 88 MiB the container used a minute after a restart.

The first-run log contains one line that looks like a failure and is not. With the config directory already owned by your UID, the ownership fix in the image finds no files to change, and chown complains that it got no file names:

chown: missing operand after ‘plex:plex’
Try 'chown --help' for more information.
Creating pref shell
Plex Media Server first run setup complete

What counts is the next line, Plex Media Server first run setup complete, so nothing needs fixing. You will also see /srv/plex/config/Library owned by root while everything under Library/Application Support/Plex Media Server belongs to your user. The script creates that parent folder as root after its ownership pass, and Plex never writes to it directly, so it ran without errors on our server and can stay as it is.

An unclaimed server only offers its setup wizard to a browser that connects from localhost, which a headless server does not have. An SSH tunnel solves that: it makes port 32400 on your workstation reach port 32400 on the server. Run this on your workstation, with your own SSH user and server address in place of klinsmann and 10.0.1.50. Port 32400 must be free on the workstation, so stop any local Plex first or the tunnel fails to bind:

ssh -N -L 32400:127.0.0.1:32400 [email protected]

Host networking obeys the host firewall, so open the main port now if UFW is active. With UFW enabled and no rule, a request from another machine to port 32400 timed out on our server; after this rule it returned HTTP 200:

sudo ufw allow 32400/tcp

That one rule covers the web app and remote clients only. LAN discovery (GDM), DLNA and Roku control stay blocked until their ports are open too, so add these when apps on your network cannot find the server:

sudo ufw allow 32410,32412,32413,32414/udp
sudo ufw allow 1900/udp
sudo ufw allow 32469/tcp
sudo ufw allow 8324/tcp

Each command answered Rule added for IPv4 and IPv6 on our server.

Leave the tunnel open and browse to http://localhost:32400/web on the workstation. The web app opens the setup route of the server and immediately hands you to the Plex account sign-in, which is the page every first run reaches:

After you sign in, the wizard names the server, offers to add libraries and then claims the server to your account; /identity switches to claimed="1". We stopped at the sign-in page because the lab server was never tied to a Plex account, so the wizard screens after it are not shown here. Opening the server on its LAN address instead of localhost led to the same sign-in page in our test, which ran in a browser on the server itself.

When you add libraries in the wizard, point them at the container paths, not the host paths. With the mounts from Step 4, movies are at /data/movies and shows at /data/tv. Our lab server, unclaimed, accepted the two libraries through its local API instead, and the first scan of 2 movies and 3 episodes finished 3.8 seconds after the libraries were created.

Error: “the server is still starting up. Please retry later”

Our very first boot answered every library request with HTTP 400 and the body the server is still starting up. Please retry later for 11.5 minutes. The server log showed the plug-in repository reaching complete after 90 seconds, detecting a change in its Plug-ins folder and restarting the whole plug-in load, which then took another 10 minutes. Two later first boots on clean config directories, one per image, finished in 75 seconds. Nothing is broken when this happens: leave the container running, poll /identity until startState disappears and then retry. We did not try restarting the container in the middle of a stall, so we cannot say whether that shortens it.

Step 6: Run Plex in bridge mode instead

Bridge mode needs every Plex port published and the host address advertised, because clients would otherwise be told the internal address of the container. The Plex firewall ports article lists what each port does:

• 32400/tcp: the server and web app. The only required port.
• 8324/tcp: Plex Companion control for Roku clients.
• 32469/tcp and 1900/udp: the DLNA server. Drop both if no DLNA client uses the server.
• 32410, 32412, 32413, 32414/udp: GDM discovery, which lets apps on the LAN find the server without signing in.

Port 3005/tcp, which older Plex Docker examples still publish, is no longer in the Plex port list or in the bridge template of the official image. Add the host address to the environment file, then open a separate file for the bridge variant:

echo "HOST_IP=$(hostname -I | cut -d' ' -f1)" >> ~/plex/.env
grep HOST_IP ~/plex/.env

The first address hostname -I prints is usually the LAN address, but on a host with Docker bridges, Tailscale or a VPN it can be another interface. Our server printed its LAN address:

HOST_IP=10.0.1.50

If yours shows a 172.17.x.x, 100.x.x.x or VPN address, edit the line in ~/plex/.env by hand. Then open a separate file for the bridge variant:

vim ~/plex/compose-bridge.yaml

Below is the bridge file the test server ran, where hostname becomes the server name shown in Plex.

services:
  plex:
    container_name: plex
    image: plexinc/pms-docker:latest
    restart: unless-stopped
    hostname: plex01
    ports:
      - 32400:32400/tcp
      - 8324:8324/tcp
      - 32469:32469/tcp
      - 1900:1900/udp
      - 32410:32410/udp
      - 32412:32412/udp
      - 32413:32413/udp
      - 32414:32414/udp
    environment:
      - TZ=${TZ}
      - PLEX_CLAIM=${PLEX_CLAIM}
      - PLEX_UID=${PLEX_UID}
      - PLEX_GID=${PLEX_GID}
      - ADVERTISE_IP=http://${HOST_IP}:32400/
    volumes:
      - ${PLEX_ROOT}/config:/config
      - ${PLEX_ROOT}/transcode:/transcode
      - ${PLEX_ROOT}/media:/data

Both files belong to the same Compose project (the plex directory), so starting the bridge file replaces the host-mode container in place:

docker compose -f compose-bridge.yaml up -d

Compose printed Container plex Recreate and the container moved to the plex_default network. Keep -f compose-bridge.yaml on every later command, including the upgrade in Step 8. A plain docker compose up -d reads compose.yaml and silently switches the container back to host mode, which is exactly what our next plain up did. If you only ever run bridge mode, put the bridge content in compose.yaml instead and drop the -f.

We first passed HOST_IP on the command line instead of putting it in .env, and every later docker compose -f compose-bridge.yaml command warned The "HOST_IP" variable is not set. Defaulting to a blank string. Keeping it in .env avoids that and keeps ADVERTISE_IP correct when Compose recreates the container. With the file above, all eight ports were listening on the host and Preferences.xml on the server carried customConnections="http://10.0.1.50:32400/", which is the advertised address clients receive.

Bridge mode also changes how the firewall behaves. With UFW active and no rule for 32400, our bridge container still answered from another machine with HTTP 200, because Docker writes its own iptables rules for published ports ahead of the UFW chains. Restrict a bridge-mode Plex with the DOCKER-USER chain or on the router, not with ufw deny.

Switching back to host mode later does not clear the advertised address: customConnections was still in Preferences.xml after our return to compose.yaml, so remove it under Settings, Network, Custom server access URLs if the address changes.

Error: The container name “/plex” is already in use

Compose identifies its containers by project and service labels, and the project name comes from the directory unless -p overrides it. A container named plex that belongs to a different project, or one started with docker run, blocks a new one and fails with Conflict. The container name "/plex" is already in use by container "1fe9acfbcecd...". We hit it with docker compose -p other up -d while the plex project was running. Run docker compose down in the project that owns it (with the same -p if one was used), or docker rm -f plex for a container started with docker run; the libraries survive because they live in /srv/plex/config, not in the container.

Step 7: Intel Quick Sync passthrough (untested)

Hardware transcoding moves video encoding from the CPU to the Intel iGPU, and Plex lists it as a Plex Pass feature. Plex Pass also matters outside the house: since April 29, 2025, remote playback of personal video needs a Plex Pass on the server owner’s account or a Plex Pass or Remote Watch Pass on the viewer’s. Our lab VM has no GPU, so this block was validated with docker compose config but never transcoded anything. On the host, confirm that an Intel driver owns the GPU and that /dev/dri exists:

lspci -k | grep -A3 -E "VGA|Display"
ls -l /dev/dri

A usable host shows Kernel driver in use: i915, or xe on the newest Intel graphics, and a renderD128 device. Then add a devices entry to the plex service in compose.yaml, below network_mode: host:

    devices:
      - /dev/dri:/dev/dri

Recreate the container with docker compose up -d, then in the web app open Settings, select your server, open Transcoder, click Show Advanced and turn on “Use hardware acceleration when available”. If you have not bought the hardware yet, the Intel chips that handle the most streams are compared in our guide to the best mini PC for Plex and Jellyfin.

Error: error gathering device information while adding custom device “/dev/dri”

Docker prints this when the device line is present but the host has no /dev/dri. Our VM has no GPU, and the full message it returned was docker: Error response from daemon: error gathering device information while adding custom device "/dev/dri": no such file or directory, with no container started. Either the host has no Intel GPU, the driver is not loaded, or, inside a VM or LXC container, the GPU was never passed through from the hypervisor. Remove the devices lines to get Plex running again, then fix the host side.

Step 8: Upgrade and back up Plex

The latest tag of the official image carries a fixed Plex build, and Plex tags each build separately (1.43.4.10903-e5521bd8c on Docker Hub during our test). Upgrading is a pull followed by a recreate, and Compose only restarts the container when the image actually changed. Bridge-mode readers add -f compose-bridge.yaml to both commands:

cd ~/plex
docker compose pull
docker compose up -d

On our box the image was already current, so Compose left the container running:

 Image plexinc/pms-docker:latest Pulling
 Image plexinc/pms-docker:latest Pulled
 Container plex Running

To hold a known-good build, replace latest in compose.yaml with a version tag from the pms-docker tags page. Plex also publishes public and beta tags that download the newest build every time the container starts; they suit a test server, not one the household relies on, because a restart can change the version without warning.

Everything Plex knows lives in /srv/plex/config: the SQLite databases, the preferences and the identity of the server. Copying it while Plex runs risks a half-written database, so stop the container for the few seconds the archive takes. The archive holds the server token that links Plex to your account, so it goes into a root-only directory, not /tmp, which Ubuntu clears at boot. Load the values from .env first, because a new shell no longer has the exports from Step 2:

set -a; . ~/plex/.env; set +a
sudo install -d -m 700 /var/backups/plex
BACKUP="/var/backups/plex/plex-config-$(date +%F).tar.gz"

Then stop Plex, write the archive, lock it down and start Plex again:

docker compose stop
sudo tar -C "${PLEX_ROOT}" -czf "${BACKUP}" config
sudo chmod 600 "${BACKUP}"
docker compose start

Our first attempt used a plex-config-*.tar.gz glob for the chmod and failed with chmod: cannot access '/var/backups/plex/plex-config-*.tar.gz': No such file or directory, because your own shell cannot list a 700 root directory to expand the glob. The BACKUP variable avoids that. The archive is now readable by root only:

-rw------- 1 root root 1854271 Oct 17 23:49 plex-config-2026-10-17.tar.gz

Our two-library server produced a 1.9 MB archive, and the container reported healthy 12 seconds after docker compose start. A real library with posters and preview thumbnails produces an archive of several GB, so send it to a disk other than the one holding /config. Restoring is the reverse: stop the container, extract the archive over /srv/plex/config and start it again. The server token (PlexOnlineToken) and the machine identifier are stored in Preferences.xml inside that folder, so a restored server keeps its identity and its link to your account, and anyone holding the archive holds that token too. The media in /srv/plex/media is not in this archive and needs its own backup.