説明
Gallery for Immich is a WordPress plugin that seamlessly integrates your self-hosted Immich photo server with your WordPress site. Display beautiful photo galleries and albums using simple shortcodes.
Key Features:
- Gutenberg Block Editor – Visual block for selecting albums, photos and settings
- Shortcode Support – Classic
[gallery_for_immich]shortcode for any editor - Display list of albums from Immich
- Display entire albums from Immich
- Beautiful responsive grid layouts
- Integrated lightbox with GLightbox
- Video playback modes (shared links, stream through WordPress, or ignore videos)
- Photos and videos on password-protected and private pages are only shown to visitors who may see the page
- Caching of album lists, album contents and photo details, with a button to clear the cache
- Flexible sorting options (date/name, ascending/descending)
- Limit the number of albums or photos shown, either the first ones or a random selection
- Single photo embedding – Display one photo with alignment (left/right/center) and configurable link behavior (lightbox, no link, or custom URL)
- Full internationalization support (Dutch, German, French translations)
- Configure Immich server URL and API key in the WordPress admin panel
Perfect for:
- Photography portfolios
- Family photo sharing
- Event galleries
- Travel blogs
- Any self-hosted photo management with Immich
Usage
Using the Gutenberg Block Editor:
The easiest way to add an Immich gallery is through the Gutenberg block editor:
- Add a new block and search for “Gallery for Immich”
- Select your display mode (all albums, single album, multiple albums, or single photo)
- Configure display options using the sidebar controls
- Customize thumbnail size and text sizes as needed
- The preview shows the shortcode that will be used
Using Shortcodes:
You can also use shortcodes directly in your content:
Display all albums:
[gallery_for_immich]
Display specific albums (comma-separated IDs):
[gallery_for_immich albums=”album-id-1,album-id-2″]
Display single album:
[gallery_for_immich album=”album-id”]
Display single photo:
[gallery_for_immich asset=”photo-id”]
Customize display options:
[gallery_for_immich show=”gallery_name,asset_description”]
Available show options (no defaults – must be explicitly specified):
* gallery_name – Show album/gallery name
* gallery_description – Show album description
* asset_date – Show photo date
* asset_description – Show photo description
Note: If the show parameter is not specified, only thumbnails are displayed without any text.
Different texts on the album page:
[gallery_for_immich show=”gallery_name” detail_show=”gallery_name,gallery_description,asset_date”]
When a visitor clicks an album in an overview, the album opens with the same show options. detail_show sets different options for that album page, using the same values as show. detail_show="" shows no text there; without detail_show, show applies to both.
Customize sizes:
[gallery_for_immich size=”300″ title_size=”18″ description_size=”15″ date_size=”12″]
Size options:
* size – Thumbnail size for albums (100-500, default: 200); max-width for single photos (100-1200, default: 200)
* title_size – Title font size (10-30, default: 16)
* description_size – Description font size (10-30, default: 14)
* date_size – Date font size (10-30, default: 13)
Single photo alignment and link behavior:
[gallery_for_immich asset=”photo-id” align=”left” link=”none”]
[gallery_for_immich asset=”photo-id” align=”right” link=”https://example.com”]
Align options: left, right, center (default: no float)
Link options: lightbox (default — opens in overlay), none (no link), or any https://... URL
Link target (custom URL only): new (default — opens in a new tab) or same (opens in the current tab)
[gallery_for_immich asset=”photo-id” link=”https://example.com/page” link_target=”same”]
Sort order:
[gallery_for_immich order=”date_desc”]
[gallery_for_immich album=”album-id” order=”description_asc”]
Available order options:
* date_desc – Newest first (default for albums)
* date_asc – Oldest first (default for photos – chronological order)
* name_asc – Alphabetically A-Z (albums only)
* name_desc – Alphabetically Z-A (albums only)
* description_asc – Alphabetically A-Z by description (photos only)
* description_desc – Alphabetically Z-A by description (photos only)
Note: Name sorting is only available for albums. Photos can be sorted by date or description.
Limit the number of albums or photos:
[gallery_for_immich album=”album-id” limit=”10″ order=”date_desc”]
[gallery_for_immich limit=”3″ pick=”random”]
limit– Maximum number of albums (overview) or photos (album), 1-1000. Omit to show all.pick–first(default) takes the first ones in the sort order;randomshows a random selection, still displayed in the sort order
For albums sorted by date, or with pick="random", only the requested photos are fetched from Immich. An album opened from a limited overview still shows all of its photos.
Show the latest photo of an album, linking to your gallery page:
[gallery_for_immich album=”album-id” limit=”1″ order=”date_desc” link=”https://example.com/gallery” link_target=”same”]
link and `link_target` work for albums with the same values as for single photos. A custom URL applies to every photo in the album; album overviews are not affected.<h3>Privacy & Security</h3>
This plugin:
* Connects to your self-hosted Immich server via API
* Does not collect or transmit any user data to third parties
* Warns when the connection to Immich is not encrypted (HTTP instead of HTTPS)
* Validates all user input and API parameters
* Uses WordPress security best practices
Your Immich server credentials (URL and API key) are stored in your WordPress database. Cached album and photo details from Immich (names, descriptions, dates, IDs) are stored there too, as transients that expire after the configured cache time. No location or camera data is cached.
Support
For issues, feature requests, or contributions, please visit:
https://github.com/vogon1/immich-wordpress-plugin
Credits
- Lightbox powered by GLightbox (https://github.com/biati-digital/glightbox)
- Integrates with Immich (https://immich.app)
スクリーンショット
ブロック
このプラグインは1個のブロックを提供します。
- Gallery for Immich Display Immich albums and single photos with lightbox, sorting, alignment, and link behavior.
インストール
- Install via WordPress admin: Plugins > Add New > Search for “Gallery for Immich”
- Click “Install Now” and then “Activate”
- Or upload the plugin files to
/wp-content/plugins/gallery-for-immich/directory and activate through the ‘Plugins’ menu
Configuration:
After activation, configure your Immich server connection:
Step 1: Create an Immich API Key
- Log in to your Immich server with the user account whose photos you want to display
- Go to Account Settings (click your profile picture in the top right)
- Navigate to API Keys tab
- Click New API Key
- Give it a descriptive name (e.g., “WordPress Plugin”)
- Set the following minimum required permissions:
album.read– Required to list and view albumsasset.read– Required to access photo metadata (EXIF data, descriptions, dates)asset.view– Required to retrieve photo thumbnailssharedLink.create– Required when using video mode ‘Shared Link’sharedLink.delete– Required when using video mode ‘Shared Link’
- Important: Only grant read-only access. Never grant write permissions for security reasons. Note: Shared links can only be created for photos and videos this Immich user owns. If you use a separate display account with albums shared to it, choose a different video mode (see below).
- Click Create and copy the generated API key
Step 2: Configure the Plugin in WordPress
- Navigate to Settings > Gallery for Immich in your WordPress admin
- Enter your Immich server URL (e.g., https://immich.example.com)
- Paste the API key you created in Step 1
- Choose Video playback mode (shared links, stream through WordPress, or ignore videos)
- Optionally change the Cache time (15 minutes by default)
- Save changes
Video playback modes:
- Shared links (default) – Creates temporary shared links on Immich. Videos stream directly from Immich and links expire automatically. Requires that the API key’s Immich user owns the videos; this mode does not work for albums that are only shared with that user.
- Stream through WordPress – Streams videos through your WordPress site, so they also play for albums that are only shared with the API key’s user. Uses the bandwidth of your WordPress server and needs
allow_url_fopenenabled in PHP, which some hosts turn off. - Ignore videos – Hides videos in galleries and only shows photos.
On password-protected and private pages, videos are always streamed through WordPress, whatever the mode, because a shared link cannot be protected by the page’s password.
FAQ
-
What is Immich?
-
Immich is a self-hosted photo and video backup solution. Learn more at https://immich.app
-
Do I need my own Immich server?
-
Yes, this plugin requires a running Immich server with API access.
-
How do I find my album or photo IDs?
-
You can find IDs in your Immich server’s URL when viewing albums or photos, or through the Immich API.
-
Does this work with localhost or an HTTP address?
-
Yes. The server URL may start with http:// or https://. For an http:// address other than localhost, the settings page asks you to confirm, because the API key and photos then travel unencrypted between WordPress and Immich. That is fine on a private network, for example when WordPress reaches Immich at its internal address; across the internet, use HTTPS.
-
Can I use a separate Immich account instead of the owner account?
-
Yes. You can create a secondary Immich account, share the albums you want to publish with it, and use that account’s API key. This keeps your main account’s credentials off the WordPress server.
One limitation: Immich only allows shared links to be created for assets a user actually owns, not for assets that are merely shared with them. Photos work normally, but videos in the default ‘Shared links’ video mode will not play for such a display account. Choose ‘Stream through WordPress’ or ‘Ignore videos’ instead. The connection & permissions test on the settings page detects this situation and explains it.
-
I added photos to an album in Immich. Why don’t they show up?
-
The plugin caches the album list, album contents and photo details for a while, 15 minutes by default. The change shows up after that time. To show it right away, click Clear cache under Settings > Gallery for Immich. You can also change the cache time there, or turn caching off.
-
Are photos on a password-protected page protected?
-
Yes. Image and video URLs are signed for the page they are shown on, and the plugin only serves them to visitors who entered that page’s password. On a private page or a draft, only logged-in users who may read it see them. Note that this protects the page, not the album: if the same album is also shown on a public page, it can be seen there.
-
The gallery shows “No photos found”, but the album has photos.
-
Log in as an administrator and look at the page again: below the message you then see the error Immich returned, for example a missing permission or an error from a proxy in front of Immich. The Test connection & permissions button on the settings page shows the same details per permission.
-
Can I customize the appearance?
-
Yes, the plugin generates standard HTML with CSS classes. You can override styles in your theme’s CSS.
-
Is the plugin translated?
-
Yes, the plugin is fully internationalized and includes translations for:
* Dutch (nl_NL) – Nederlands
* German (de_DE) – Deutsch
* French (fr_FR) – FrançaisAdditional translations can be contributed via .po files in the languages directory.
評価
貢献者と開発者
変更履歴
0.10.0
Release Date – 17 October 2026
- Tested against WordPress 7.1.3 and Immich v3.3.3
- New: photos and videos on password-protected and private pages are protected too. Image URLs are signed for the page they are shown on, and only served to visitors who may see that page. Videos on such pages always stream through WordPress. Membership plugins can add their own rule with the
gallery_for_immich_can_viewfilter - New: caching of the album list, album contents and photo details, 15 minutes by default, configurable, with a “Clear cache” button
- New: support for the structured search API of Immich 3.2 and later, which Immich 4 will require; older Immich versions keep working
- Improved: the connection test shows what Immich actually answered for a failed check, and the Immich server version
- Improved: administrators see the Immich error on a gallery that cannot be loaded; visitors see a plain message instead of the raw error
- Improved: the image proxy passes on the real image type (thumbnails are WebP), and answers 502 when Immich cannot be reached
- Changed: the video mode “Proxy via fopen” is now called “Stream through WordPress”; the setting itself is unchanged
- Security: every image and video URL is signed, so the proxy only serves what your site displays
- Fix: in Safari, the seek bar of a video in the lightbox did not work
- Fix: album overviews showed “Error from Immich API: 1” when Immich returned an error
- Fix: Live Photos did not play on sites with plain permalinks
- Fix: the video proxy passed an error page from Immich on as a video
- Uninstalling the plugin now also removes its cached data
0.9.0
Release Date – 24 September 2026
- Tested against WordPress 7.1.2 and Immich v3.2.2
- New:
limit=andpick=— show only a number of albums or photos, the first ones in the sort order or a random selection. For albums sorted by date, or withpick="random", only the requested photos are fetched from Immich (issue #13) - New:
detail_show=— choose different texts for the album page that opens when a visitor clicks an album in an overview - New:
link=also works for albums, so e.g. the latest photo of an album can link to your full gallery page - New:
link_target=— open a custom link in the same tab or a new tab (default) (issue #6) - Improved: the block editor only offers the sort options that apply to the chosen display mode, and explains that “Multiple albums” keeps the order in which you select them
- Security: an album page opened from a URL is now limited to the albums the shortcode actually shows
- Security: the Live Photo endpoint only serves videos of photos shown on the site, and shared links for videos are reused instead of created on every page view
- Security: the image proxy no longer serves original files, and only streams videos in the “Proxy via fopen” mode
- Fix: block editor translations could fall back to an older version after a build
0.8.2
Release Date – 3 September 2026
- Tested against WordPress 7.1 and Immich v3.1
- Fix: Photos rotated, cropped or filtered in Immich showed their original, unedited version. The plugin now requests the edited render (
edited=true, Immich v2.5+) (issue #15) - Fix: Edited photos stayed stale in visitors’ browsers because proxied images are cached for a year. Image URLs now carry the asset’s modification timestamp, so an edit in Immich becomes visible right away
- Fix: A video that could not be shared aborted the page halfway through rendering. The gallery now falls back to showing the thumbnail without a lightbox link
- Fix: The connection test reported
sharedLink.createas missing for an Immich user who can see an album but does not own it. This is now shown as a warning with an explanation instead of a false negative
0.8.1
Release Date – 4 July 2026
- Fix: Album detail pages showed “No photos found” on Immich v3+ (removed
assetsfrom the album API response); assets are now fetched via the metadata search endpoint (issue #14)
0.8.0
Release Date – 23 May 2026
- New:
link=attribute for single photos — lightbox (default), no link, or custom URL - New: Single photos always display the Immich preview image;
sizecontrols max-width (up to 1200px) - New:
align=attribute for single photos — left, right, or center for text wrapping - Fix: Image proxy output buffering issue and CSS typos (PR #11)
- Fix: Connection test false negatives on Immich v2.7+ (PR #12)
0.7.0
Release Date – 13 April 2026
- New: Apple Live Photos support — play button in the lightbox for photos with a Live Photo video component
- New: Connection & permissions check button on the settings page
- New: HTTP server URLs are now allowed (with a confirmation warning modal)
- Removed:
asset.downloadis no longer a required API permission
0.6.1
- Fix for missing album list.
0.6.0
Release Date – 16 February 2026
- New: Video playback modes (shared links, proxy via fopen, ignore videos)
- Improved: Video handling for editor/preview and shared link cleanup
0.5.0
-
Release date 17 December 2025*
-
New: Support for videos from Immich
- For single asset: define alignment to allow text around the asset
0.4.0
Release Date – 10 December 2025
- New: Gutenberg block “Gallery for Immich” with visual editor
- New: Full Gutenberg block support with all shortcode features
- New: Full translation support for Dutch, German, and French
0.3.3
Release Date – 9 December 2025
- WordPress.org compliance improvements
- Fixed: Removed direct file access
- Fixed: Added translation support for plugin name and description
- Updated: License changed to GPLv3 for consistency
- Improved: Image proxy now uses query parameters instead of direct PHP files
- Improved: glightbox in its own namespace
0.3.1
Release Date – 29 November 2025
- Added flexible sorting with order parameter (none, date_asc, date_desc, name_asc, name_desc)
- Albums can be sorted by date or name, ascending or descending
- Photos can be sorted by date (ascending/descending) or use Immich’s original order
- Default sorting: albums newest first (date_desc), photos oldest first (date_asc/chronological)
- Uses standard database terminology (asc/desc)
- WordPress.org compliance: bundled GLightbox locally (no CDN dependencies)
- Removed load_plugin_textdomain() – WordPress.org handles translations automatically
- Removed debug error_log() calls for production
- Full WordPress Plugin Check compliance with zero errors
- Ready for WordPress.org plugin directory submission
0.3.0
Release Date – 29 November 2025
- WordPress.org compliance: bundled GLightbox locally (no CDN dependencies)
- Removed load_plugin_textdomain() – WordPress.org handles translations automatically
- Removed debug error_log() calls for production
- Full WordPress Plugin Check compliance with zero errors
- Ready for WordPress.org plugin directory submission
0.3.0
Release Date – 29 November 2025
- Disabled zoom functionality in lightbox (removed confusing zoom icon)
- Improved lightbox user experience with cleaner interface
- Code hardening for enhanced security
- Enhanced documentation with API key setup instructions
- Added security and privacy information in README
- Added access control documentation
- Updated installation instructions with detailed API key permissions
0.2.1
Release Date – 29 November 2025
- Enhanced security: UUID validation for all IDs
- Added HTTPS enforcement for production
- Improved input sanitization and validation
- Added timeout settings for API requests
- SSL verification enabled
- Better error handling and logging
- Security headers for image proxies
- Sanitization callbacks for settings
- Capability checks for admin access
0.2.0
Release Date – 27 September 2025
- Added photo sorting by dateTimeOriginal (chronological order)
- Added album sorting by endDate (newest first)
- Improved photo descriptions in lightbox
- Added EXIF date display
- Enhanced grid layouts with CSS Grid
- Added hover effects and animations
- Portrait photo support with object-fit
0.1.0
Release Date – September 2025
- Initial release
- Basic album and photo display
- GLightbox integration
- Shortcode support
- Internationalization support
- Dutch translation included