Deploy Plex Media Server With Docker
Running Plex in Docker isolates it from the host system, makes updates and rollbacks trivial, and standardizes deployment across different Linux distributions, NAS devices, and virtual machines. This guide covers the full deployment process — from pulling the image to configuring GPU passthrough for hardware transcoding.
Why Docker for Plex
- Clean upgrades: Update by pulling a new image. Roll back by switching to the previous tag. No package manager conflicts.
- Portable configuration: Your entire Plex setup is defined in a docker compose file and a config volume. Move it to a new server by copying two things.
- Isolation: Plex runs in its own container with its own dependencies. It cannot conflict with other services on the host.
- Reproducibility: The same compose file produces the same setup every time. No manual configuration steps to forget.
Choosing a Docker Image
Two main options:
- plexinc/pms-docker: The official image from Plex. Well-maintained, tracks stable releases.
- linuxserver/plex: Community image from LinuxServer.io. Adds PUID/PGID support for file permissions, automatic updates, and a consistent configuration interface shared with other LinuxServer images. Many users prefer this for its permissions handling.
Both images work well. This guide uses the LinuxServer image because its permissions model prevents the most common Docker deployment headache.
Docker Compose Setup
Create a directory for your Plex deployment and a docker-compose.yml file:
mkdir -p /opt/plex
cd /opt/plex
Create the compose file with this configuration:
version: "3.8"
services:
plex:
image: lscr.io/linuxserver/plex:latest
container_name: plex
network_mode: host
environment:
- PUID=1000
- PGID=1000
- TZ=America/New_York
- VERSION=docker
volumes:
- ./config:/config
- /mnt/media/movies:/movies
- /mnt/media/tv:/tv
- /mnt/media/music:/music
restart: unless-stopped
Key Settings Explained
- network_mode: host: Plex uses host networking for DLNA, local network discovery, and optimal performance. This avoids NAT issues that bridge networking causes.
- PUID/PGID: Set these to the user ID and group ID that owns your media files. Run
idon the host to find your UID/GID. This ensures the container can read your media and write to the config directory. - TZ: Your timezone. Affects log timestamps and scheduled tasks.
- volumes: The
/configvolume stores the Plex database, metadata, and settings. The media volumes (/movies,/tv,/music) map to your host's media directories. Use absolute paths on the host side.
Starting and Claiming the Server
docker compose up -d
Open http://server-ip:32400/web in a browser. Sign in with your Plex account to claim the server. Configure your libraries by pointing them at /movies, /tv, and /music (the container paths, not the host paths).
GPU Passthrough for Hardware Transcoding
Hardware transcoding requires passing the host's GPU into the Docker container.
NVIDIA GPUs
- Install the NVIDIA Container Toolkit on the host:
apt install nvidia-container-toolkit
nvidia-ctk runtime configure --runtime=docker
systemctl restart docker
Add to your compose file under the plex service:
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities: [gpu]
Intel Quick Sync
Intel integrated GPUs are accessed through the /dev/dri device. Add to your compose file:
devices:
- /dev/dri:/dev/dri
Ensure the container's user has permission to access the render device: add the user to the render group on the host, or set the device permissions with udev rules.
Enabling in Plex
After passing the GPU through, enable hardware transcoding in Plex: Settings > Transcoder > Use hardware acceleration when available. This requires Plex Pass.
Volume Mount Best Practices
Config Volume
Always use a named volume or a bind mount to a specific directory for config. Never let Docker manage the config volume anonymously — you need to be able to back it up and migrate it.
The config directory contains the Plex database (all your watch history, metadata, and settings). Back it up regularly.
Media Volumes
Mount media as read-only if Plex does not need to write to it:
- /mnt/media/movies:/movies:ro
This prevents Plex from accidentally modifying your media files. Remove :ro if you use Plex features that write to media directories (like storing extras or chapter thumbnails alongside files).
Transcode Temp Directory
Plex writes temporary files during transcoding. By default, these go into the config volume. For better performance, map the transcode temp directory to a fast drive (SSD or tmpfs):
- /tmp/plex-transcode:/transcode
Then in Plex settings, set the transcoder temporary directory to /transcode. Using tmpfs (RAM disk) for transcodes is the fastest option if you have enough RAM:
tmpfs:
- /transcode:size=8g
Networking Options
Host Networking (Recommended)
Host networking (network_mode: host) is the simplest and most reliable option. The container shares the host's network stack directly — no port mapping needed, DLNA works, and there is no NAT overhead.
Bridge Networking
If you need network isolation, use bridge mode with explicit port mappings:
ports:
- 32400:32400/tcp
- 1900:1900/udp
- 32469:32469/tcp
- 32410:32410/udp
- 32412:32412/udp
- 32413:32413/udp
- 32414:32414/udp
Bridge mode may break DLNA discovery and GDM (G'Day Mate) network discovery. Local clients may not automatically find the server. You will need to manually add the server by IP.
Updates and Maintenance
Updating Plex
docker compose pull
docker compose up -d
This pulls the latest image and recreates the container. Your config volume is preserved — no data loss. If the update causes issues, roll back:
docker compose down
docker compose up -d --force-recreate
Pin to a specific version tag in the compose file for stability: image: lscr.io/linuxserver/plex:1.40.0 instead of :latest.
Automatic Updates
Use Watchtower to automatically update the Plex container:
docker run -d --name watchtower -v /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower --cleanup --interval 86400
Watchtower checks for new images daily and recreates containers with the latest version. Add --monitor-only if you want notifications without automatic updates.
Common Deployment Mistakes
- Wrong PUID/PGID: If Plex cannot read your media files, the container user does not match the file owner. Run
ls -la /mnt/media/on the host and match the UID/GID in your compose file. - Relative paths in volumes: Always use absolute paths.
./configworks but can cause confusion if you rundocker composefrom a different directory. - Forgetting to claim the server: After first start, claim the server immediately at
http://server-ip:32400/web. If you wait too long and the claim token expires, you may need to set the PLEX_CLAIM environment variable. - Running as root: Avoid running the container as root. The LinuxServer image's PUID/PGID system handles permissions correctly without root access.
Platform-Specific Notes
Synology NAS
Synology DSM has Docker support (Container Manager). Import the compose file or create the container through the UI. Set the PUID/PGID to match your Synology user (usually 1026 for the first user). Mount shared folders as volumes.
Unraid
Unraid has a Docker UI with community templates. Search for "Plex" in the Community Applications plugin — the LinuxServer template is pre-configured. Set the network type to Host, map your media shares, and configure the GPU device if applicable.
TrueNAS SCALE
TrueNAS SCALE uses Kubernetes for containers but also supports Docker Compose through custom apps. Create a docker-compose.yml as shown above. Map ZFS datasets as the media volumes. GPU passthrough works through the TrueNAS app configuration.