Wetin PUID and PGID Do for Docker Compose
PUID and PGID no be Docker settings. See why linuxserver.io images create bind-mount files as 911:911, plus the command to fix ownership.
Wetin PUID and PGID really mean
PUID and PGID na two environment variables wey some container images read when dem dey start. Docker itself no dey check dem. Na convention wey linuxserver.io images and small number of other images dey use. So, if image no dey written to read dem, e go silently ignore dem.
Inside linuxserver.io image, user dey wey dem call abc. Dem create am when dem build the image, with UID (user ID) 911 and GID (group ID) 911. Container dey start as root, run its init scripts, and one of those scripts change the user ID before the application start:
groupmod -o -g "${PGID}" abc
usermod -o -u "${PUID}" abcThe -o flag allow ID wey another process don already use. After that, init script drop privileges and run the application as abc. So Docker pass PUID=1000 enter the container like any other environment variable, and e no dey act on am. The variable change the user ID inside the container before the application start. This mean say for standard rootful daemon without user namespace remapping, newly created files normally go land for your disk with owner ID 1000. Writing to an existing writable file no change the file owner. Rootless Docker dey shift that number, as we explain further down. If you leave PUID unset, abc go keep 911. Na why bind mount wey you never configure fit fill with files wey get 911:911 as owner.
Get your two numbers with id
Run this for the host, as the user wey own the data directories:
iduid=1000(deploy) gid=1000(deploy) groups=1000(deploy),27(sudo),988(docker)uid na your PUID and gid na your PGID. For script, id -u and id -g go print the numbers alone. For most fresh VPS images, the first human account na 1000:1000, but no assume say na so. Allocation dey depend on the accounts and configuration wey dey present: rebuilt server fit allocate 1000 again, while later account fit get higher available ID. If your services dey run under dedicated service account instead of your own login user, run id thatuser and take the numbers from there.
Why your files dey show as 911:911
ls -l dey print numeric ID instead of name when no host account match that ID. If no host account match UID 911, no name dey to print. Use ls -ln to see numbers every time and remove the confusion:
ls -ln /srv/appdata/sonarrdrwxr-xr-x 2 911 911 4096 Aug 7 09:12 Backups
-rw-r--r-- 1 911 911 512 Aug 7 09:12 config.xmlThat output match the container built-in defaults, but existing files alone no prove which user the application dey run as now. The config.xml for that listing na also the file wey hold the authentication settings. This matter the first time you open the web UI and find say Sonarr and Radarr release without default username or password. Confirm am from inside the container instead of guessing:
docker exec sonarr id abc
docker compose logs sonarr | head -n 25The linuxserver init dey print the result for the startup log as two lines:
User UID: 911
User GID: 911If those lines read 911 after you set PUID=1000 for your Compose file, the running container no dey use the value wey you set. The usual cause na say you edit docker-compose.yml and then run docker compose restart, wey reuse the existing container with the original environment. Environment changes need docker compose up -d, wey recreate the container. The other cause na deliberate: when an image dey run for read-only or non-root mode, the init skip the renumbering completely, even though the variable dey inside the container. For read-only mode, the banner report the unchanged ID of abc; for non-root mode, e report the owner of /run.
Why you no fit delete file wey container write
Kernel dey compare numbers, e no dey compare names. Your shell dey run as UID 1000. File belong to UID 911. Directory wey hold am na drwxr-xr-x and e too belong to 911, so group and other get read and execute but dem no get write. To delete file, you need write permission for its directory, not for the file, so na why you dey see this even when the file itself look harmless:
rm: cannot remove '/srv/appdata/sonarr/config.xml': Permission deniedContainer wey dey write go hit the same problem from the other side. If host directory belong to your user with mode 755 and application dey run as 911, its first write go fail with Permission denied and app go report am with its own wording. For .NET application like Sonarr or Radarr, e go show as UnauthorizedAccessException: Access to the path '/data/downloads' is denied. Permission string wey dey before the file tell you which of the three permission sets system dey use judge you with, and how to read drwxr-xr-x correctly na wetin make that error change from confusing to obvious.
This one na bind mount problem specifically. When Docker create an empty named volume and mount am over path wey dey exist for image, e copy the path contents enter the volume, including ownership and permission bits, so application go find directory wey e already own. Bind mount no get this treatment: Docker mount your host directory exactly as e be. That difference na one practical reason why you need know when bind mount better pass named volume and when e no be better.
Fix directory wey don already wrong
Setting PUID and PGID go change wetin the application dey do from now. E no go go back fix every file wey dey disk already, although the init go correct ownership for specific paths wey dey describe below. Stop the stack, correct the ownership yourself, then start am again:
docker compose down
sudo chown -R 1000:1000 /srv/appdata/sonarr
docker compose up -dUse sudo chown -R "$(id -u):$(id -g)" /srv/appdata/sonarr if you no wan type the numbers. Do this when the container don stop, because application wey dey write at that time fit run into recursive chown and leave directory tree half-corrected, then cause another confusing round of errors.
Wetin PUID and PGID no fit fix
Na here people wey do everything correct dey usually get problem. The linuxserver base image user setup script dey chown three paths when e start: /app, /config and /defaults. Your media mounts no dey that list. /data, /downloads and /tv dey go the application without any change. So, if ownership for the host side of those mounts no allow the container user to write, the container go start cleanly, show the correct UID for the banner, then fail for the first import.
Na the correct behaviour be that. If e run recursive chown across twelve terabyte media library every time container start, e go cause serious problem. This mean say you need manage the media directories yourself. Na those mounts be where permission problems dey happen. This kind failure fit show quietly for application log hours after container don look healthy. Periodic write test wey you connect to ntfy for your own VPS, wey dey push alerts go your phone na cheap way to know about the problem before one week of missing episodes expose am.
Ways to control user identity, and when each one fit apply
PUID and PGID environment variables
This one dey work only for images wey their entrypoint dey read dem. E popular because container still dey start as root, do its own setup, fix /config, then drop privileges. Docker Mods and custom init scripts still dey work. The cost na say you dey trust convention instead of platform feature, and variable names no standard across projects.
The user: key for Compose
This one na real Docker feature, and e dey work for every image because container runtime apply am before the image own code start:
services:
sonarr:
image: lscr.io/linuxserver/sonarr:latest
user: "1000:1000"The process no dey run as root at all, not even for small time, and this na real security gain. E also break anything for the entrypoint wey need root. For linuxserver images, the project support this on reasonable endeavours basis and only for images wey dem don test. The specific caveats be say PUID and PGID no get effect again, Docker Mods no go run, custom services no go run, and na you go handle permissions for every mounted volume. Their documented pattern join the flag with writable /run:
user: 1000:1000
tmpfs:
- /run:uid=1000,gid=1000,exec
security_opt:
- no-new-privileges=trueOne cosmetic side effect dey surprise people. Numeric user: wey no get matching entry inside container /etc/passwd go make tools inside report whoami: cannot find name for user ID 1000. The ID valid and file access dey work normally. Na only name lookup dey fail.
Rootless Docker
Rootless Docker dey run the daemon itself as your unprivileged user, so daemon and containers dey run without host root privileges. E change the ownership calculation completely. Container UID 0 dey map to the host UID of the user wey dey run rootless Docker. Container UID n for any n of 1 or more dey map to subuid + (n - 1), where subuid na the base of the range wey dem allocate to you for /etc/subuid; group IDs follow the same rule with /etc/subgid. Docker expect at least 65,536 subordinate IDs there.
Read that mapping again because e turn the usual advice upside down. With rootless Docker, when container create file as root, the file normally go belong to you. When container create file as UID 1000, the file normally go belong to subordinate ID, such as 100999 when the range start at 100000. Your shell access depend on permissions and ACLs. Deletion normally depend on the containing directory, so you fit delete the file from directory wey you control. So the PUID value wey correct for rootful daemon na wrong one here. The two mechanisms change ownership for different layers, and if you stack dem without checking, you fit lose write access to the mounted data. If you choose rootless, test the ownership of one file wey you write on your own server before you migrate library enter am.
For most self-hosted stacks on one VPS, PUID and PGID for rootful daemon na the practical choice because na wetin the images build for and document. Use user: when the image README talk say dem don test that image for am, or when you dey run official upstream image wey no support PUID at all. A document workspace like one self-hosted AFFiNE instance for one VPS dey for that last case because none of its containers dey read PUID, and runtime—not anything for environment block—dey determine ownership of its database directory and uploaded files. Same thing apply to one self-hosted Chatwoot support desk, where Rails container and Sidekiq worker both dey write to one uploads directory, and neither one dey read PUID. So that directory must match the user wey image already dey run as. This no change for newer stack either. So giving each person for the team their own sandboxed OneCLI agent leave each person's workspace directories and Postgres data directory owned by the user wey each image already dey run as. That make am a user: and chown problem, not PUID problem. Put one self-hosted API in front of Codex, Claude Code and Hermes and its entrypoint go manage several identities: container must start as root, console and gateway go run as unprivileged user, and each agent session go run as its own user. No add user: to that deployment; its entrypoint dey handle the data volume ownership.
The media stack matter: one group wey containers dey share
An arr media stack wey get Sonarr, Radarr and one download client na where this matter stop to be theory. The download client dey write finished file inside /data/downloads. Sonarr then dey hardlink or move that file go /data/media. For hardlink to work, the two containers need write access to the same tree. If download client dey run as 1000 while Sonarr dey run as 1001 without shared group write permissions, one of dem go own files wey the other one fit only read.
The fix na shared group wey every container for the stack dey use as its PGID:
sudo groupadd -g 13000 media
sudo usermod -aG media deploy
sudo chown -R deploy:media /srv/media
sudo find /srv/media -type d -exec chmod 2775 {} +
sudo find /srv/media -type f -exec chmod 0664 {} +The leading 2 for 2775 na setgid bit. For directory, e mean say every new file and subdirectory wey dem create inside go inherit group media instead of the creator own primary group. So, new downloads go continue to work without you running chown again. Log out and log in again, or run newgrp media, before you check your own access. Group wey you add with usermod -aG no dey show for shell session wey already open.
Inside the container, groupmod -o -g 13000 abc dey renumber abc group to 13000, so abc dey write with the same GID as your host media group. Every linuxserver container wey dey access this tree keeps its own PUID and shares that one PGID. This includes containers further down the chain wey only read the finished library, like Jellyfin itself. Front end like Halcyon, wey dey serve that library like video store for the 90s wey you fit browse, dey connect to Jellyfin over HTTP with HALCYON_JELLYFIN_URL. Its standard deployment no need the shared media PGID or media-directory mount.
Then set UMASK=002 for every linuxserver container inside the stack. Na this step plenty people dey miss. If you leave am unset, the application keeps the umask wey e inherit unless something else changes am. The example value wey the image READMEs show na UMASK=022. With effective umask of 022, application wey request 0666 for new file go get 0644 when default ACL no dey. The rest of the group fit still read am, but dem no fit change am. This go undo most of the sharing wey you just configure. With 002 and no default ACL, application wey request the usual 0666 for files and 0777 for directories go get 0664 files and, inside the setgid tree, 2775 directories. The group go get write access. Umask only dey remove bits, so application wey request 0600 still go get 0600. Directory wey carry default ACL no dey follow umask at all. Add the variable beside PUID and PGID:
services:
sonarr:
image: lscr.io/linuxserver/sonarr:latest
container_name: sonarr
environment:
- PUID=${PUID}
- PGID=${PGID}
- UMASK=002
- TZ=Etc/UTC
volumes:
- /srv/appdata/sonarr:/config
- /srv/media:/data
restart: unless-stoppedPut those two values inside a .env file beside the Compose file, so the whole stack go read one definition:
PUID=1000
PGID=13000Compose dey read that file automatically for ${PUID} style substitution. Na the same method wey you use for credentials. The practice of keeping values out of docker-compose.yml and putting dem inside .env file still apply here. The difference na say these two numbers no be secret.
Verify everything end to end instead of trusting the config. Write new file as the application's user, apply the configured umask, then read am from the host. Use test filename wey no already exist:
docker exec --user abc sonarr sh -c 'umask "$UMASK" && touch /data/downloads/permtest'
ls -ln /srv/media/downloads/permtestHealthy result go show your PUID as the owner, 13000 as the group, and -rw-rw-r-- as the mode. If the group reads 1000, run ls -ldn /srv/media/downloads. Either the setgid bit — the s inside drwxrwsr-x — dey missing from that directory, or the directory itself still belongs to group 1000 instead of media. The chown and chmod 2775 commands above go fix both. If the mode reads -rw-r--r--, check the container UMASK value and the directory default ACL. Recreate the container if its environment still dey stale. This test checks file creation as abc with the configured mask. The application's own creation mode and effective umask still determine its files. Remove the test file with rm /srv/media/downloads/permtest when you finish.
Which images dey use which variable
linuxserver.io images dey use PUID, PGID and UMASK. Paperless-ngx dey use different names for the same idea: USERMAP_UID and USERMAP_GID, and both dey default to 1000. Its documentation tell you to read dem from id -u and id -g. Photo servers dey show the same difference: PhotoPrism get its own PHOTOPRISM_UID and PHOTOPRISM_GID pair, while Immich no ship any equivalent. E leave the container user to Docker user: key. So, choosing between PhotoPrism and Immich also decide which of these mechanisms you go maintain for the biggest library for the server. Many official upstream images, including common database and web server images, ship with a fixed built-in user. Dem expect you to use user: or leave the setting as e be. Small single-app deployments raise the same question. So, when you set up a self-hosted openGym workout tracker, check which user the container actually dey run as before you point a bind mount to am. The directory wey hold its database go inherit that user, whether you set PUID or not. Remote access relay dey fall into the same category. So, when you run your own RustDesk relay server, the Ed25519 key pair wey hbbs write for first start go enter your bind mount owned by the user wey that image use. You fit correct am later with host-side chown, or choose the identity from the start with user: key. That image no set its own user, as long as the mounted directory writable by the ID wey you choose. The same thing apply to infrastructure wey you add later. So, putting Authentik in front of your apps for one login means say you dey run official authentik and Postgres images wey no read PUID at all. Their volume ownership come from the users wey their processes run as and the setup wey their entrypoints perform. Authentik remove its Redis dependency for release 2025.10.
So check the README for each image before you copy an environment block from one project to another. Docker go pass any environment variable wey you set into any container, whether anything inside dey read am or not. A PUID wey nothing dey use no go produce error, warning, or effect. The container go start as the user Docker select through user: setting or the Dockerfile. Then its entrypoint fit drop privileges before e start the application. Read this information before you add anything new to the server, including a self-hosted open-kritt security scanning stack. The Compose file go show whether the images support PUID, or whether the images themselves fix the ownership of the directories wey you mount.
FAQ
Why my Docker files dey owned by 911:911?
911 na the UID and GID of the abc user wey dey built into linuxserver.io images. If you see am, e match the built-in defaults, but files fit still keep that ownership after you change the container PUID and PGID. ls -l dey show the raw numbers when no account for your host match those IDs, so no name dey to display. Set PUID and PGID to the output of id, recreate the container with docker compose up -d, then fix the existing files with sudo chown -R 1000:1000 for the affected directory.
PUID and PGID dey work for every Docker image?
No. Dem no be Docker feature, and Docker no dey read dem. Dem dey work only for images wey their own entrypoint dey read dem and call usermod and groupmod before e start the application. Na the linuxserver.io family and some projects wey copy the pattern dey do this. Other projects dey use different names, like USERMAP_UID and USERMAP_GID for paperless-ngx. For image wey no dey read either one, the variables go get accepted and ignored without any warning.
Make I use PUID and PGID or the user: key for Docker Compose?
Use PUID and PGID when the image supports dem, because the entrypoint still dey run as root long enough to fix /config and start its own services correctly. Use user: when the image documentation confirms support for the user wey you choose. If PUID support no dey, that alone no mean say the entrypoint fit work without root. For linuxserver image, setting user: go make PUID and PGID inactive, stop Docker Mods and custom services from running, and make permissions for every mounted volume your responsibility.
Sonarr get the correct PUID but e still no fit move files. Wetin be the problem?
Check three things in order. First, check the media mount itself: the base image user setup script dey chown /app, /config and /defaults, so /data or /downloads go keep whatever ownership e get for the host. Second, check the shared group: give containers wey dey access the media tree the same PGID and group write permissions. Third, check the umask: effective mask of 022 go produce 0644 files when the application request 0666 and no default ACL apply. This one mean say other containers for the group fit read the files but no fit modify dem. If you leave UMASK unset, e no guarantee any particular mask or file mode. Set UMASK=002 and set the setgid bit on the directories with chmod 2775 so new files inherit the group. Application wey request 0600 still go create private files, and default ACL go change how creation permissions dey assigned.