Immich on Synology: Install & Setup Guide
Install Immich on Synology with Container Manager. Plan local database storage, existing photo libraries, firewall access, backups and project updates.
On this page
Direct Answer
Use Synology Container Manager to create a Compose project from Immich's release files, with explicit persistent folders for media and PostgreSQL. Establish LAN access and a small successful upload before adding external libraries, proxy access or acceleration. The Synology instructions hosted by Immich are a community contribution, not an official Synology-platform support guarantee from the Immich team. Synology community guide ↗
Check your NAS architecture, memory and CPU capabilities first. Current Immich supports amd64/arm64, recommends local SSD database storage, and forbids a network-share PostgreSQL data directory. v3 amd64 machine learning requires x86-64-v2 or later. Model-specific Container Manager availability and GPU support must be checked on the actual NAS. Requirements ↗
Reviewed with stable v3.2.2 ↗ on September 16, 2026. Keep project data and configuration backed up before updates. Cleanup/rebuild controls can differ by DSM version and volume type; never assume a button named Clean is harmless to every deployment.
Who this setup is for and what you need
This path suits an existing Synology owner who wants DSM to manage the application while keeping the database, managed uploads and original photo shares separate. It assumes your model offers Container Manager in Package Center. If it does not, do not install an unrelated model's package to force compatibility.
Reserve at least 2 CPU cores and 6 GB available memory for normal Immich operation; 4 cores and 8 GB are recommended. Leave capacity for DSM and other NAS workloads. The restricted 4 GB option requires disabling machine learning. Confirm amd64/arm64 compatibility and, on amd64, the v3 machine-learning CPU requirement before importing a large collection. Current resource requirements ↗
The intended architecture is one Container Manager project containing the official Compose services, backed by dedicated NAS-local folders. Your existing Synology Photos folder remains an optional external library, not the destination for new Immich uploads. Start on the LAN with a few disposable test photos; add remote access only after storage and backups work.
Step 1: Prepare Container Manager and shared storage
Install Container Manager through DSM Package Center. In File Station, use the Docker shared folder and create immich-app, with library and postgres subdirectories. This follows the community guide's layout. If you use a different shared folder or volume, record its actual absolute path rather than assuming every Synology uses /volume1. Synology installation ↗
| Folder/configuration | Purpose | Check before importing |
|---|---|---|
| Project directory | Compose file and .env | File Station and Container Manager point to the same project |
library | Managed Immich upload storage | New directory with sufficient space; not the existing family photo share |
postgres | Live PostgreSQL state | Local NAS filesystem with suitable permissions, not a remote SMB/NFS mount |
| Existing photo shared folder | Optional external library | Separate read-only mapping and explicit library owner |
| Backup destination | Recoverable DB/media copies | Independent from the only working NAS copy |
A NAS's own local volume and a remote network share mounted on that NAS are different. Putting the database on the latter remains unsupported. If the local database really is on spinning disks, the community guide points to DB_STORAGE_TYPE: 'HDD' under the database service in Compose; this is tuning, not permission repair. Database requirements ↗
Step 2: Place and edit the release files
Download docker-compose.yml and example.env from the release linked by the official Compose installation ↗. Upload them into the project directory and rename example.env to .env. DSM Text Editor may require temporarily using a .txt extension; restore the exact .env filename when finished.
Set UPLOAD_LOCATION and DB_DATA_LOCATION to the intended directories, choose a random alphanumeric DB_PASSWORD, and select the intended IMMICH_VERSION such as stable v3 or exact v3.2.2. Preserve default database name/user unless deliberately customized. Keep the two files from the same release and do not download repository-main configuration.
The reviewed v3.2.2 configuration maps the upload directory to /data inside immich-server; PostgreSQL uses its own data mount. Existing NAS pictures should be added as a separate external mount. Do not replace /data with your existing photo share to “import” it. Release configuration ↗
| Setting | Decision before building |
|---|---|
UPLOAD_LOCATION | Dedicated managed-media folder; the documented layout uses ./library |
DB_DATA_LOCATION | Dedicated local database folder; the documented layout uses ./postgres |
IMMICH_VERSION | An intentional release selection; pinning v3.2.2 makes this review reproducible |
DB_PASSWORD | New random alphanumeric secret; keep it in the protected .env |
Relative paths above belong to the project directory. They are not external-library import paths. See the Compose configuration walkthrough for the complete release-file and environment procedure rather than copying an old all-in-one YAML from a NAS forum.
Step 3: Create and build the project
- In Container Manager, open Project → Create.
- Select the prepared project directory and choose its existing Compose file.
- Review the file/environment configuration and proceed through the wizard.
- Skip the Web Station portal step for the basic direct-port installation, as shown in the community guide.
- Complete the build/start operation and inspect the project's containers and logs.
Expected: the server, ML, cache and database containers start without repeated exits. If the project cannot parse the file, check its filename, .env placement and YAML edits before changing filesystem access. If PostgreSQL fails, inspect that container's log and database path rather than repeatedly rebuilding. Container Manager walkthrough ↗
Step 4: Establish LAN access and firewall rules
Open http://NAS-IP:2283 from a browser on the same LAN. If DSM firewall rules restrict communication, inspect the actual container IP/network in Container Manager and follow the community guide's Control Panel → Security → Firewall → Edit Rules workflow for the necessary traffic to port 2283. Use the actual addresses; a recreated project can get different container addresses.
The guide offers a fixed Docker subnet as an optional way to stabilize firewall matching. Before adopting its example network, check for overlap with your LAN, VPN and other Docker networks. Its configuration connects all relevant services to the same network; adding a custom network to only the server can isolate it from its dependencies. Synology firewall and fixed subnet guidance ↗
Do not turn a local connectivity test into a broad public firewall opening. Verification is that the intended LAN client reaches the application and the services communicate, not merely that DSM accepted a rule.
Step 5: Create the admin and test mobile upload
Choose Getting Started in the web UI and register the first user, which becomes admin. Create other accounts through Administration → Users. Install the mobile app, enter the reachable server URL, sign in, select a small photo album and enable backup. Post-installation ↗
Default backup is Wi-Fi-only. iOS controls background scheduling, while Android battery restrictions can stop background work. First test with the app open, then evaluate background behavior separately. Mobile Backup ↗
Verification: open the test files from the web UI, download an original, play a short video and check processing jobs. These are acceptance checks based on the documented workflow, not a claim that every Synology model has been tested. If only search/faces fail, inspect machine-learning processing separately from upload.
Step 6: Add an existing NAS photo folder
Use the external-library tutorial to add a read-only volume under immich-server. Preserve the internal upload mount. The host side is the real shared-folder path; the library's import path is the destination inside the container. Create the library as an administrator, select its owner, add that container path and scan a small test directory. External Libraries ↗
| Failure | Check | Expected result |
|---|---|---|
| NAS folder visible in File Station but scan finds nothing | Container mount destination, import path, parent-directory traversal and read access | A known sample appears and its original opens |
| Only some files fail | Exclusions, supported format and server job logs | The corrected sample scans and processes |
| New NAS files do not appear automatically | Scheduled scan; network file watching is unreliable | A manual scan finds the test file, then the next scheduled scan does too |
| Metadata changes revert | Read-only sidecar restrictions | Do not expect XMP writes through a read-only mount |
Backup and update the existing project
Protect a database dump, all managed originals, external photo shares and the project configuration. The automatic dump inside UPLOAD_LOCATION/backups does not include the photographs. A dump and originals stored only on the same NAS are still vulnerable together. Follow the complete backup and restore procedure.
For an update, identify current and target versions, read release notes and compare the target Compose changes with your customized file. Preserve .env, directories, external mounts and network rules. Use the community guide's project stop/rebuild sequence only after understanding the installed DSM controls and backup coverage. Re-check container addresses after rebuild, then test login, original download, upload and ML jobs. Synology update section ↗, Immich upgrade rules ↗
After those checks, the community update sequence is:
- Select the existing project and use Action → Stop.
- If your verified storage layout and current confirmation dialog permit the documented cleanup, use Action → Clean. Stop here if the dialog includes data you have not independently protected.
- The community guide next uses Image → Remove Unused Images. Review the scope before removing cached images. With the reviewed YAML and preserved
.envin place, use Project → Action → Build, then ensure the project starts; the guide describes Build starting it, while DSM controls can differ. - Inspect container logs and actual network addresses, then repeat the original-download and mobile-upload checks from Step 5.
A build that fails or a container that restarts repeatedly has not completed the update. Retain the previous configuration and recovery set and follow the specific failure branch below. Community update sequence ↗
v3 adds the CPU and VectorChord requirements described in the update tutorial. Do not apply an old pgvecto.rs image or a generic community updater simply because it once worked on another NAS.
If this does not work
| Symptom | Next check | Avoid assuming |
|---|---|---|
| Project fails immediately | Compose syntax, .env location and container-specific startup logs | Rebuilding will fix a wrong path |
| UI stops working after rebuild | Current IP/subnet and DSM firewall rule, then server log | Every restart loop means database corruption |
| PostgreSQL permission failure | Local filesystem and exact DB path/access | The photo-share ACL is also appropriate for PostgreSQL |
| ML HTTP500 / connection failures | ML logs, shared service network, actual backend and hardware | Renaming underscore/dash or clearing cache is a confirmed universal fix |
| Image preview fails | Original versus thumbnail, external mount and job error | ML failure necessarily explains all image failures |
Use image troubleshooting for the last branch. When reporting an unresolved problem, include NAS model, DSM version, Immich/server/mobile versions, deployment method and redacted relevant logs.
FAQ
Can I use a 4 GB or older Synology model?
The official restricted 4 GB option disables machine learning, while normal minimum memory is 6 GB. You must still meet architecture/runtime requirements; no single RAM answer establishes compatibility for every NAS model. Requirements ↗
Will pointing UPLOAD_LOCATION at Synology Photos import my collection?
No. Keep managed uploads separate and expose the existing photo folder through an external-library mount. Import the container-visible path in Immich, then scan a small folder before indexing everything. A read-only mount is a useful starting point when another application also manages those originals.
Does Container Manager Clean replace a backup?
No. It is part of the documented project rebuild procedure, not a recovery mechanism. Verify the exact confirmation dialog and persistent storage before using it. Keep a recoverable database dump and media copy independently of the project being rebuilt.
Sources
- Synology installation ↗ — Community contribution hosted in Immich docs.
- Requirements ↗ — Official Immich platform limits.
- Compose installation ↗ — Official Immich release files/environment.
- v3.2.2 Compose file ↗ — Official release configuration.
- Post-installation ↗ — Official Immich account setup.
- Mobile Backup ↗ — Official Immich phone behavior.
- External Libraries ↗ — Official Immich mounts/scans.
- Upgrading ↗ — Official Immich version/migration policy.
- Container Manager Project ↗ — Official Synology Project controls; consult the help for your DSM version.