Audit and fix file permissions across your *arr Docker stack on macOS
_{Permissions are the #1 headache with Docker media stacks on macOS.
This tool finds and fixes permission issues before they break your setup.}

The Problem

File permissions are the most common issue with Docker media stacks on macOS. Every other post on r/selfhosted and r/radarr is someone debugging why Sonarr can't write to their download folder or Radarr can't move files after import.

The usual causes:

• PUID/PGID set differently across containers
• Volume mounts owned by root instead of your user
• macOS privacy controls blocking Docker's disk access
• .env file missing or has stale user IDs

This script audits everything in one pass and tells you exactly what's wrong.

What It Checks

Check	What It Looks For
Runtime detection	OrbStack or Docker Desktop installed and running
PUID/PGID consistency	All containers using the same user/group IDs
.env validation	PUID/PGID set and matching your current user
Volume permissions	Host directories owned by the expected user
Full Disk Access	Best-effort macOS privacy check + runtime bind-mount probe
Compose config	docker-compose.yml exists and is parseable

Quick Start

git clone https://github.com/liamvibecodes/mac-media-stack-permissions.git
cd mac-media-stack-permissions
bash fix-permissions.sh

Or run directly:

curl -fsSL https://raw.githubusercontent.com/liamvibecodes/mac-media-stack-permissions/main/fix-permissions.sh | bash

Usage

# Audit only (default, no changes made)
bash fix-permissions.sh

# Audit a custom media directory
bash fix-permissions.sh --path /Volumes/Media

# Fix all permission issues
bash fix-permissions.sh --fix

# Fix with custom path
bash fix-permissions.sh --fix --path /Volumes/Media

# Allow fixes for compose mounts outside --path
bash fix-permissions.sh --fix --allow-outside-media-dir

See It In Action

Demo

Fix mode demo

Fix Mode

Run with --fix to automatically resolve permission issues:

• Runs chown -R on directories with wrong ownership
• Reports what was changed
• Protects paths outside --path by default (use --allow-outside-media-dir to override)
• Exits non-zero only if unresolved failures remain after fixes

The script never modifies docker-compose.yml or .env. It only fixes file ownership on disk.

Works With

• mac-media-stack — One-command Plex + Sonarr + Radarr setup
• mac-media-stack-advanced — Power-user setup with transcoding, quality profiles, and automation

Author

Built by @liamvibecodes

License

MIT