Setting up
Fixing UID and GID Permissions in Docker Music Stacks
The symptom is always the same: Aurral downloads a file, the music server can read it, and your own file manager cannot. That is a permissions problem, and PUID and PGID are the fix.
Why the mismatch happens
Containers run as root by default. Anything they write on a mounted volume is owned by root. Your music server also runs as a container and may be running as root too, so playback works fine, while your file manager on the host — running as your user — cannot touch the file.
PUID and PGID tell Aurral which host user and group to run as, so everything it writes belongs to you. It is a two-minute setting that avoids a much longer cleanup later.
Finding the right numbers
On Linux or macOS, id -u and id -g print the numbers directly. On a NAS, the admin user usually has id 1000 and group 1000, which is why that appears in most examples.
- id -u gives the user ID.
- id -g gives the primary group ID.
- Run them as the user who will own the music, not as root.
Fixing files that are already wrong
Changing PUID and PGID affects new writes. Files already on disk keep their old owner. To fix them, change ownership on the host for the affected directories rather than deleting anything.
- Find your IDs with id -u and id -g.
- Update the environment values in your compose file.
- Recreate the container so it picks the new values up.
- Change ownership of existing downloaded files on the host.
- Re-run a library scan so availability updates.
| Situation | Command |
|---|---|
| Linux or macOS | sudo chown -R user:group /path/to/downloads |
| NAS with a UI | Use the file manager's ownership or ACL settings |
| Verify afterwards | ls -ln /path/to/downloads |
Windows and mixed hosts
Windows has no Unix permission model, so the host-ownership problem does not arise in the same way. Path mismatches replace it as the common failure. Storage checks are the fastest way to tell the two apart.
Frequently asked questions
My music server reads the files but I cannot. Is that a bug?
No. Your media server runs as root or as its own user, so it can read root-owned files that your host user cannot. PUID and PGID align ownership with your user.
Will changing PUID and PGID break existing playback?
No. Playback reads files, and ownership does not block reads for a server running as root. New writes land with the correct owner from that point on.
Should I use root to avoid the problem?
You can, but then every file on disk belongs to root, which causes the same class of problem in other tools. Setting PUID and PGID to a normal user is the better long-term choice.
Ready to set it up
One container and one media path is genuinely all it takes. Everything else in this page is something you add when the need appears.