Immich Bridge

Move your Google Photos library into Immich, at your own pace.

Immich Bridge gives family members a guided web interface for a migration that would otherwise require command-line tools. Connect an Immich account, prepare a Google Takeout export, upload its ZIP files, preview the results, and choose when to import. Immich-Go does the importing inside an isolated processing container.

What the person moving their photos sees

1. Connect your account. The administrator sets the Immich address. Bridge helps you sign in there first, create a personal API key and confirm the destination account. Bridge does not create an Immich account for you.
2. Prepare your export. A walkthrough explains Google Takeout and downloading the original ZIP files. Keep every part of the same export together.
3. Upload your ZIPs. Upload everything at once, or do it in batches if your computer is short on space. Pause and return later; accepted bytes stay saved. After reopening the browser, select the same original files to resume them.
4. Review the full collection. Analysis starts only after every ZIP has arrived. A photo and its metadata may be in different ZIPs. ZIP integrity is separate from preliminary metadata coverage; a filename candidate count does not predict import success.
5. Preview, then import. The preview does not change your Immich library. Results explain what was processed or skipped. When ready, confirm the destination and start the actual import.

Analysis, preview and import show saved server activity and a confirmed Stop lifecycle. You can leave server work running and optionally request an email for that operation when a relay and verified owner address are available. See activity and private logs and task email.

A skipped item is not automatically a lost photo: it may be a duplicate or an item excluded by your options. Bridge shows the reason when available and says when it is unknown. “Processed” does not necessarily mean “newly uploaded”—an item may already exist or need metadata handling. Support reports contain counts and reason codes, not your filenames, account details or API key.

Keep your original export until you have checked the photos in Immich. Bridge is a migration tool, not a backup. Stopping an import does not undo photos already imported; interrupted imports never restart automatically. Deleting a Bridge collection removes its staging data, not your Immich photos.

Is it ready for me?

The local walkthrough, isolated processing and production HTTPS template have passed their tests. The source is published, the license is selected, and the matching importer source archive is packaged. Before hosting for other people, work through the release and installation checklist. It separates completed development work from the checks for your images and server.

The default setup listens on localhost. It does not create a domain or public route.

This release supports Google Photos Takeout ZIP files. Apple/iCloud imports, server-folder imports, open registration and self-service password recovery are not included. Reviewed integration: Immich 3.3.5 and Immich-Go 0.32.0 with the Bridge reporting/security rebuild. This is a tested combination, not a claim that every newer release is compatible.

Try it on your computer

You need Docker with Linux containers and Docker Compose. The runner requires Engine API v1.56 with volume-subpath support; use a compatible current Engine. On Windows, install Docker Desktop; the helper below also needs Python 3. Use a small test export before trying your entire library.

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\start-local.ps1

The helper builds the application and creates a private, ignored .env file with a random initial password and encryption key if one does not already exist. Read the credentials locally, then open http://localhost:8080. The first local account is the administrator. Existing settings and data stay in place; rerunning the helper does not reset an existing password.

For Linux or a manual setup, copy .env.example to .env, choose a 16–72 byte initial password, and generate a cryptographically random base64-encoded 32-byte BRIDGE_CREDENTIAL_KEY. Keep that key safe: it protects saved credentials. Then run:

docker compose build processor runner app
docker compose up -d

In Administration → Configuration → Immich, set your HTTPS Immich address. Restart the application to apply destination connection settings. Turn on Enable import worker with Allow previews only first; the walkthrough explains how to permit real imports after the test. Each person connects with their own Immich key. See the local walkthrough for exact setup steps, a synthetic sample export and recovery checks.

To stop, use docker compose down. Your data stays in Docker's named volumes. Do not add --volumes unless you intend to erase it. Never commit .env, passwords, API keys or uploaded photos. Saved administrator settings override initial environment defaults; administration and recovery explains how that works.

Before hosting it for other people

Use the production guide, not the local-development defaults. Bridge works with an HTTPS reverse proxy of your choice; it does not require a particular identity provider, domain, DNS service or hosting company.

Storage needs special attention. Bridge keeps the complete export on the server until processing and cleanup; uploading in batches only reduces the space needed on the user's computer. Default limits are 64 GiB per ZIP, 192 GiB per account and 256 GiB shared staging, with another 30 GiB reserved as headroom. Paused uploads still reserve space. Administrators can configure these limits. Docker's free-space estimate is not a guarantee of free space on the host drive.

Keep staging separate from Immich media. Use a filesystem that supports file locking, atomic renames and hard links; do not assume an SMB share will work. SQLite must stay on local storage. A native ARM64 pilot is still a release check.

What runs behind the scenes?

Part	What it does
App	Serves the website and API; manages accounts, settings and migration history.
SQLite	Stores those records and encrypted credentials under /data.
Staging	Keeps partial and complete ZIP uploads under /staging.
Valkey	Stores the analysis work queue so work can continue after you close the browser.
Runner	A private, trusted service that starts and removes isolated processing containers. Only it receives Docker socket access.
Processor	A temporary container that reads one collection's inputs and runs verification, analysis or Immich-Go.

The runner is deliberately privileged to control Docker and must never be exposed as a public service. Processors do not receive the Docker socket, the application database or users' saved Immich keys. Read processing isolation for the exact controls and their limits.

Find the right instructions

I want to…	Read this
Try a migration locally	Local walkthrough
Manage users, branding or settings	Administration and recovery
Connect Immich or understand import options	Immich connection and imports
Set up single sign-on or email	OIDC · SMTP and warning text
Understand upload cleanup	Retention and collection deletion
Host the application	Production guide · Release checks
Develop, test or investigate security	Architecture · Tests · Security implementation
Set up automated build gates	Forgejo CI and runners
Understand result and support reports	Migration results
Check merged pilot changes and remaining verification	Integration status · Installation checks

License and attribution

Immich Bridge is AGPL-3.0-only; see LICENSE. Commercial use is allowed under its terms, with the applicable source-sharing obligations. Immich-Go and other dependencies retain their own licenses and notices. See third-party licensing and matching importer source.

This project is independent of Immich and Immich-Go.