Media Picker for Immich

GYIK

What is Immich?

Immich is a self-hosted photo and video management solution, similar to Google Photos. It runs on your own server and provides AI-powered search, facial recognition, and more.

What is the difference between „Use” and „Copy”?

Use Selected creates a virtual attachment that serves images and videos through your WordPress server as a proxy — no files are stored locally. This keeps your WordPress uploads directory lean.

Copy Selected downloads the full original file into wp-content/uploads/ as a standard WordPress attachment. Use this when you want a local copy independent of your Immich server.

Does my Immich server need to be publicly accessible?

Your Immich server must be accessible from your WordPress server, but it does not need to be publicly accessible on the internet. The plugin proxies all media through WordPress, so visitors never connect to Immich directly.

Which Immich API key permissions does the plugin need?

Grant the API key these five permissions — nothing else is required:

• asset.read — list asset metadata and run library searches (browse, search by query, search by person).
• asset.view — stream thumbnails and video playback through the proxy.
• asset.download — fetch full-resolution originals for the proxy and the Copy/import path.
• person.read — populate the people filter dropdown and people thumbnails.
• album.read — list albums in the picker and fetch their assets for the Album Gallery block.

The same list is shown inline on the Settings page and the per-user profile API key field for easy copy-paste into Immich.

Can different users have their own API keys?

Yes. If no site-wide API key is set in Settings > Immich, each user can add their own key on their Profile page. The proxy serves media using the key of the user who added the asset.

How does the proxy cache work?

When a proxied image or video is requested for the first time, the plugin fetches it from Immich and saves a copy in wp-content/cache/immich/. All subsequent requests are served from the local cache without contacting your Immich server. To enable automatic cleanup, check Cache Cleanup in Settings > Immich and set a lifetime in hours (default 24). When disabled, cached files are kept indefinitely.

Does the lightbox work automatically?

Yes. Posts containing proxied Immich images automatically get a lightbox. Clicking an image opens the full-resolution original in an overlay. Press Escape or click anywhere to close.

How do I embed a whole Immich album in a post?

Add the „Immich Album Gallery” block from the inserter, click „Pick album”, and choose an album from your Immich server. The gallery renders live and is cached for 5 minutes; you can override per-block options like columns, image size, sort, and lightbox in the block sidebar.

For large albums where the global cap (default 100) trims the rendered set, the block has an optional „Show ‘View on Immich’ link” toggle that appends a link to the album in the Immich web UI. Leave it off unless your Immich URL is reachable from your visitors’ browsers — many self-hosted setups put Immich behind a VPN or on a Docker-internal hostname that won’t resolve outside the LAN.

I use Nginx — do I need extra server config?

Yes. The plugin caches proxied Immich binaries under wp-content/uploads/immich-cache/, and the proxy endpoint enforces post-status authorisation on every request. On Apache the plugin drops a deny-all .htaccess into that directory automatically so nothing else can serve the cached files. Nginx ignores .htaccess, so you need an equivalent rule in your site’s server block:

location ^~ /wp-content/uploads/immich-cache/ { deny all; return 404; }

Without that, a visitor who captured a cached asset URL from rendered HTML could fetch the file directly even after the post is unpublished or made private.