Set Up Plex with Docker Compose: Step-by-Step Guide
Docker Compose is the most popular way to run Plex Media Server alongside other services like Sonarr, Radarr, and Overseerr. A single compose file defines your entire media stack — Plex, download clients, library management, and monitoring — and brings it all up or down with one command. This guide covers the Plex container setup, common pitfalls, and how to integrate it with the rest of your media automation stack.
Prerequisites
Before writing your compose file, make sure these are in place:
- Docker and Docker Compose: Install Docker Engine (not Docker Desktop for servers) and the Docker Compose plugin. On Ubuntu:
sudo apt install docker.io docker-compose-v2. Verify withdocker compose version— you want v2.x or later - Plex claim token: To link the new server to your Plex account, generate a claim token at plex.tv/claim. This token expires in 4 minutes, so generate it right before running the container for the first time. You only need this once — after the initial setup, Plex remembers the account association
- Directory structure: Create directories for Plex config and media before starting the container. A common layout is
/opt/plex/configfor Plex's database and configuration, and/media(or wherever your library lives) for the actual media files. Keep config on SSD for performance; media can be on HDD
Basic Plex Docker Compose file
This minimal compose file gets Plex running with the essential settings:
- Image: Use
plexinc/pms-docker:latest(the official Plex image) orlinuxserver/plex:latest(the LinuxServer.io community image, which adds convenience features like PUID/PGID user mapping). Both work well; the LinuxServer image is more popular in the self-hosting community - Network mode: Set
network_mode: hostfor the simplest setup. Host networking lets Plex use your server's network directly, avoiding NAT issues with remote access and DLNA discovery. If you need network isolation, use bridge mode with port 32400 mapped - Environment variables: Set
PLEX_CLAIMto your claim token (first run only),TZto your timezone (like America/New_York), andPUID/PGIDto match the user that owns your media files (avoids permission issues) - Volumes: Mount at least two volumes — one for Plex config (
/opt/plex/config:/config) and one or more for your media library (/media/movies:/movies,/media/tv:/tv). The config volume stores the database, metadata, and preferences. The media volumes are read-only unless you want Plex to modify files - Restart policy: Set
restart: unless-stoppedso Plex automatically restarts after a crash or server reboot, but stays stopped if you intentionally stop it
GPU passthrough for hardware transcoding
If your server has an NVIDIA GPU or Intel Quick Sync, passing it to the Docker container enables hardware transcoding (requires Plex Pass):
- NVIDIA GPU: Install the NVIDIA Container Toolkit on the host. In your compose file, add the
runtime: nvidiadirective and setNVIDIA_VISIBLE_DEVICES=allin the environment. Alternatively, use thedeploy.resources.reservations.devicessyntax in newer Compose versions. Verify withdocker exec plex nvidia-smiinside the running container - Intel Quick Sync: Pass the Intel GPU device to the container by adding
/dev/dri:/dev/drito the devices section. The LinuxServer Plex image automatically detects and uses Intel hardware transcoding when the device is available. Verify by checking that/dev/dri/renderD128exists inside the container - Permissions: The container user must have access to the GPU device. With LinuxServer images, set PUID/PGID to a user in the
videoandrendergroups on the host. Without correct permissions, Plex silently falls back to CPU transcoding
Multi-service media stack
The real power of Docker Compose is running your entire media automation stack in one file. Common services alongside Plex:
- Sonarr: Monitors for new TV show episodes and automatically downloads them via your preferred download client. Mount the same media volume as Plex so completed downloads appear in your library automatically. Use the LinuxServer Sonarr image for consistency
- Radarr: Same as Sonarr but for movies. Monitors wishlists, searches for releases, and downloads them. Same volume mount strategy — Radarr and Plex share the same media directory
- Prowlarr: Indexer manager that connects Sonarr and Radarr to torrent and Usenet indexers. Centralizes indexer configuration so you manage it in one place instead of configuring each app separately
- Overseerr: Request management interface that lets users request movies and TV shows. Integrates with Sonarr and Radarr to automatically search for and download requested content. Provides a clean web UI for family and friends to request media
- Tautulli: Monitoring and statistics for Plex. Shows who is watching what, streaming history, bandwidth usage, and notification alerts for new content or playback issues. Essential for multi-user servers
- Download client: qBittorrent or SABnzbd depending on whether you use torrents or Usenet. Runs in its own container with its own volume mounts for incomplete and completed downloads
Volume mount strategy
Getting volume mounts right is the most common source of problems in Docker media stacks:
- Shared root: Mount all media under a single root path that all containers share. For example, mount
/data:/datain every container, with subdirectories like/data/movies,/data/tv, and/data/downloads. This enables hardlinks and instant moves between the download client and media library, saving disk space and time - Hardlinks and atomic moves: When Sonarr or Radarr imports a completed download, it can create a hardlink (no extra disk space) or do an instant atomic move instead of copying the file — but only if the source and destination are on the same filesystem and the same Docker volume mount. If downloads and media are on separate mounts, the app must copy the file, which is slower and uses double the disk space temporarily
- NAS mounts: If your media is on a NAS, mount the NFS or SMB share on the host first, then pass the mount point to the containers. Do not mount NAS shares directly inside containers — it complicates troubleshooting and can cause permission issues
Networking considerations
Docker networking affects how Plex discovers devices on your network and how remote access works:
- Host networking (recommended): With
network_mode: host, Plex behaves as if it is running directly on the host. DLNA discovery, GDM (Plex's device discovery protocol), and remote access all work without additional configuration - Bridge networking: If you need network isolation between containers, use bridge mode and map port 32400 to the host. DLNA and GDM require additional ports (1900/udp for DLNA, 32410-32414/udp for GDM). Remote access works with port 32400 mapped but requires explicit configuration in Plex settings
- Custom network: For multi-service stacks, create a custom Docker network so containers can communicate by service name. This is essential for Sonarr to reach Prowlarr, Overseerr to reach Sonarr and Radarr, and Tautulli to reach Plex — all by container name instead of IP
Maintenance and updates
Keeping your Docker Plex stack updated and backed up is straightforward:
- Update all containers: Run
docker compose pullto fetch the latest images, thendocker compose up -dto recreate containers with the new images. Config volumes persist across container recreations - Backup: Back up the Plex config directory regularly. This contains your database, watch history, metadata, and server preferences. The media files are separate and have their own backup strategy. A simple tar or rsync of the config directory is usually sufficient
- Logs: View Plex logs with
docker compose logs plex. Add-fto follow logs in real-time. If Plex is misbehaving, the logs are the first place to check — common issues like permission errors, missing media paths, and transcoder failures all show up clearly - Watchtower (optional): Run the Watchtower container to automatically pull and restart containers when new images are published. This keeps Plex and all your media apps updated without manual intervention. Some users prefer manual updates for more control over when changes happen
Need Expert Help?
Our team has handled thousands of cases. Get a fast, honest diagnosis.
Get Started →