Google Photos to Immich: the Takeout import, step by step

To move Google Photos into Immich, export your library with Google Takeout as zip files, then upload all the zip parts in one run with immich-go's upload from-google-photos command. Immich's own documentation points Takeout users to that community tool rather than the official CLI, because immich-go pairs each photo with the JSON metadata Google puts beside it, so albums, descriptions and locations survive the move.

Don't unzip the archives. Don't drag them into the web uploader either. Everything below comes from the Immich docs, the immich-go docs and Google's Takeout help page.

#Before you start

• A running Immich server. If you haven't installed it, follow Immich's Docker Compose guide. The short version: download docker-compose.yml and example.env from the latest release, set UPLOAD_LOCATION to a directory with plenty of free space, change DB_PASSWORD (letters and digits only), and run docker compose up -d. The current example.env sets IMMICH_VERSION=v3. The latest release is 3.2.4, published 28 September 2026.
• Enough RAM. With machine learning on, Immich needs at least 6 GB and recommends 8 GB, so a Raspberry Pi 5 needs the 8 GB or 16 GB board. The Immich profile has the details.
• Disk space for three copies, for a while: the zips, the imported library, and Immich's thumbnails and transcodes (the Immich docs estimate those at roughly 10–20% of the library).
• A backup of your Takeout. The immich-go README says: "Keep a backup copy of your files for safety." It also calls the tool "an early version, not yet extensively tested."

#Step 1: request the Takeout

1. Go to takeout.google.com. Google pre-selects every product that holds your data. Uncheck everything except Google Photos.
2. Select Next step.
3. Under Export type, choose One-time archive. (Scheduled exports repeat every 2 months for a year. That's useful later for catching new photos.)
4. Under File type, choose zip. immich-go's best-practices page recommends ZIP, and warns: "Don't mix ZIP and TGZ formats in the same import."
5. Under Archive size, pick the largest option. Google splits bigger exports into several archives, and immich-go recommends the maximum (50 GB) "to minimize parts."
6. Create the export.

Expected result: Google emails you a link. Its help page says this "could take from a few minutes to a few days," and that most people get the link the same day.

#Step 2: download every part

Download all the archives into one folder, for example ~/takeout/. They're numbered takeout-001.zip, takeout-002.zip and so on. Check that none are missing:

ls -la ~/takeout/takeout-*.zip

That check is the first item in immich-go's troubleshooting list, and it matters. A photo's JSON sidecar and the photo itself can land in different zip parts. immich-go matches them up only when it sees every part in the same run.

Google also notes that changes you make while the export is being built (such as adding or deleting photos or albums) may not be included. So stop reorganising your library until the import is done.

#Step 3: register the Immich admin user

If this is a fresh server, open http://<machine-ip-address>:2283, click Getting Started, and register. The first user to register becomes the admin (Immich's post-install docs). If family members will have their own libraries, create their accounts now as well. Each person imports their own Takeout with their own API key.

#Step 4: create an API key

In Immich's web interface, open your user settings and create an API key. The Immich CLI docs note you can restrict the key's permissions. immich-go's installation docs list the permissions it needs:

asset.read, asset.statistics, asset.update, asset.upload, asset.copy, asset.delete, asset.download, album.create, album.read, albumAsset.create, server.about, stack.create, tag.asset, tag.create, user.read

immich-go pauses Immich's background jobs during the upload (--pause-immich-jobs defaults to true). For that, the key must be admin-linked and also have job.create and job.read.

Treat the key like a password. Delete it in Immich when the migration is done.

#Step 5: install immich-go

immich-go is a single binary: "No NodeJS or Docker required." Run it on the computer that holds the zips, not necessarily the server. Download the build for your system from the releases page. The latest release is v0.32.0, published 25 June 2026, and its README says it's compatible with Immich V2 and V3. Then extract it:

tar -xzf immich-go*.tar.gz
sudo mv immich-go /usr/local/bin/   # optional: put it on your PATH

On Windows, unzip it with Explorer instead.

#Step 6: do a dry run

--dry-run is a documented upload option that simulates the upload "without actual transfers." Run it first and read the summary:

immich-go upload from-google-photos \
  --server=http://your-ip:2283 \
  --api-key=your-api-key \
  --dry-run \
  ~/takeout/takeout-*.zip

This is the README's Takeout command with --dry-run added and the path changed to the folder from step 2.

#Step 7: run the import

Drop --dry-run. For a large library, immich-go's best-practices page gives a "conservative approach for maximum reliability":

immich-go upload from-google-photos \
  --server=http://your-ip:2283 \
  --api-key=your-api-key \
  --concurrent-tasks=4 \
  --client-timeout=60m \
  --pause-immich-jobs=true \
  --on-errors=continue \
  --session-tag \
  ~/takeout/takeout-*.zip

The docs pitch that one at 100k+ photos. For 10k–100k they suggest --concurrent-tasks=8 plus --manage-raw-jpeg=StackCoverRaw --manage-burst=Stack. The server URL and path are the only changes from the docs' example.

A few defaults worth knowing, from the command reference:

Expected result: immich-go creates the albums on the server and uploads the assets with their metadata. Duplicate detection means files already in Immich are skipped.

#Step 8: check, then let Immich catch up

Browse the timeline and a few albums in Immich. Check the dates on some old photos, because dates are the first thing a bad import gets wrong. Once the upload ends and the paused jobs run again, Immich works through its backlog (thumbnails, and face detection and smart search if machine learning is on). On a small machine, expect that backlog to take a while.

Keep the Takeout zips until you're satisfied. Only then think about deleting anything from Google Photos. Google's help page states that downloading your data "doesn't delete it from Google's servers."

#Troubleshooting

These come from immich-go's own docs and issue tracker.

• Lots of files weren't imported. Check that every zip part is present. Then retry with --include-unmatched, which imports files without matching JSON. If a Takeout looks incomplete, immich-go suggests requesting a new one: "Some Google takeouts may be incomplete."
• Some albums are missing, but their photos arrived. Issue #1277 documents this case: the album's metadata sits in a folder with no assets, and the photos are in another zip. Passing all parts together (takeout-*.zip) is the documented approach. If an album still doesn't appear, that open issue is the place to check.
• The import stopped halfway. It's "safe to restart": immich-go detects existing files and skips duplicates. --session-tag tags each run so you can see what came in when, and the log files show where it stopped.
• Uploads time out on big videos. The default server timeout is 20 minutes. The large-library example raises it with --client-timeout=60m.
• Permission errors from the server. Recheck the API key's permissions against the list in step 4. job.create and job.read are needed for pausing jobs.

#What to do next

• Set up the Immich mobile app's backup so new photos go to your server instead of Google.
• Get an alert if the server goes down: monitor it for free with Uptime Kuma.
• Still weighing your options? See Immich vs PhotoPrism and the wider Google Photos alternatives list.
• Running it on a Pi? Raspberry Pi self-hosted apps covers what else fits alongside.