Install
Set up Photostead
One person in the household sets up the Photostead server, once. Everyone else just opens it in a browser or pairs their iPhone. Pick where your server will run.
What it needs
- A computer that stays on: a NAS, a home server or mini PC, a Raspberry Pi 5, or a Mac or Windows PC. No GPU is needed.
- 4 GB of memory, 8 GB for a big library.
- Room for thumbnails and the database: about 0.65 GB for every 1,000 photos and videos, on fast storage if you have it. Your originals stay where they are.
Unraid
-
Make a share named
photosteadunder Shares: Primary storage the cache, Secondary storage the array, Mover action cache → array. Your originals live here, protected by parity. -
Install Photostead from the Apps tab: search for Photostead and choose Install. If it isn’t listed yet, open Unraid’s
terminal (the >_ button at the top right), run this, then choose Docker → Add Container → Template →
Photostead:
wget -O /boot/config/plugins/dockerMan/templates-user/my-Photostead.xml https://raw.githubusercontent.com/atomtanstudio/photostead/main/deploy/unraid/ca/photostead.xml -
Point it at photos you already have (optional): map each folder read-only to
/libraries/<name>, for example/mnt/user/pictures→/libraries/pictures. Photostead indexes them in place and never writes to them. - Choose Apply, then open the WebUI (port 4800).
Docker, on a NAS or Linux box
compose.yaml is everything in
one file. Change the folders on the left of each volume, and set PUID and PGID to the user who owns them. Then:
- Synology: Container Manager → Project → Create, and paste it in.
- Portainer: Stacks → Add stack.
- TrueNAS or CasaOS: add it as a custom app.
- Anywhere else:
docker compose up -din its folder.
Then open port 4800 on that machine in your browser. Or with Docker alone:
docker run -d --name photostead -p 4800:4800 --shm-size=1g --stop-timeout 60 \
-v /srv/photostead-data:/data \
-v /srv/photos/photostead:/photos \
-v /srv/photos/existing:/libraries/existing:ro \
ghcr.io/atomtanstudio/photostead:latest
/data holds the database, thumbnails and previews. /photos is where uploads and phone backups are filed, a
folder for each person. Folders under /libraries/ are indexed in place, read-only. Images are built for 64-bit x86 and ARM.
Mac
For a Mac with Apple silicon (M1 or later) and macOS 26 Tahoe or later.
- Download Photostead for Mac.
- Open it and drag Photostead to Applications.
- Open Photostead from Applications. Its house icon appears in the menu bar at the top of the screen.
- Choose Open Photostead from that icon to open it in your browser.
Uploads and phone backups go to Pictures › Photostead Library (Choose Another Folder… in the menu changes it). Turn on Open at Login and Keep This Computer Awake so phones can back up overnight.
Windows
For 64-bit Windows 10 or 11.
- Download Photostead for Windows.
- Right-click the download, choose Extract All, and put the Photostead folder somewhere it can stay, such as your user folder.
- Open the folder and double-click Photostead.
- If Windows says it protected your PC, choose More info → Run anyway. If it asks whether Photostead may use your network, allow private networks, so your phone can reach it at home.
- Photostead’s icon appears in the tray by the clock (under the ^ if it’s hidden). Choose Open Photostead from it.
Uploads and phone backups go to Pictures\Photostead Library. Turn on Open at Login and Keep This Computer Awake in the tray menu so phones can back up overnight.
Once it’s running
- Create the first account. It’s the admin.
- Follow the Get started checklist at the top of the timeline: bringing photos in, backing up a phone, reaching Photostead away from home, inviting the household and keeping a second copy. Each step ticks itself off once it’s done.
- Pair your iPhone: install Photostead for iPhone from the App Store, then open Devices & remote access → Show a pairing code (on a Mac or PC, Pair a Phone… in the menu) and point the iPhone’s Camera at the QR code. More on pairing.
The first time it starts, Photostead downloads its AI models (about 2.4 GB). Search by meaning and faces start working once they’re in.
Away from home
In Devices & remote access, choose Tailscale: Photostead joins your tailnet with a secure address of its own. Turn on Funnel there and share links work for anyone, and paired iPhones work from anywhere with nothing else to install, so only the person who sets Photostead up needs Tailscale. Behind your own reverse proxy or Cloudflare Tunnel instead, see the guide.
Source code
Photostead is free and open source, under the GNU Affero General Public License v3. The code, the full guide, releases and issues are on GitHub. A gaming PC can lend its GPU for faster indexing: see the optional GPU worker there.
Stuck?A person reads every email.
Email us