# immich-go: uploading Google Photos takeouts and local folders to Immich without Node.js

> immich-go is a Go binary that uploads local folders, Google Photos takeouts, iCloud exports and other Immich servers into a self-hosted Immich instance. It avoids the Node.js dependency of the official CLI, and the README itself warns it is early software.

**simulot/immich-go** — An alternative to the immich-CLI command that doesn't depend on nodejs installation. It tries its best for importing google photos takeout archives.

- Repository: https://github.com/simulot/immich-go
- Stars: 6,957 · Forks: 259
- Language: Go
- License: AGPL-3.0
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/simulot-immich-go

## The gap immich-go fills for self-hosted Immich users

Immich is a self-hosted photo server. Getting an existing library into it is the awkward part. The official immich-CLI is distributed as a Node.js package, so a machine that only runs the Immich Docker container still needs a Node runtime before it can push a single file. immich-go is a single Go binary that talks to the same server API and removes that dependency. The README states the project requires no NodeJS and no Docker, and the repository ships pre-built binaries for Windows, macOS, Linux and FreeBSD through its GitHub releases page.

The audience is narrow and specific. You need a running Immich server with API access and an API key that holds the permissions listed in docs/installation.md. If you are still deciding whether to run Immich at all, this tool is downstream of that decision. The other group it targets is people leaving Google Photos: the from-google-photos command reads a takeout archive and matches each media file with the JSON metadata Google ships beside it, so albums, descriptions and locations survive the move instead of collapsing into one flat dump.

## How immich-go reads a takeout and writes to the server

The tool is a CLI built on cobra, with commands arranged as verb plus source. Upload commands are from-folder, from-google-photos, from-immich, from-picasa and from-icloud. Archiving runs in the other direction: archive from-immich pulls assets off a server and writes them to a folder.

The data flow for a takeout is the interesting part. Google exports a ZIP containing the media files plus a JSON sidecar per file. immich-go walks the archive, pairs each file with its sidecar, and converts that metadata into API calls: create the album, attach the asset, carry over the description and the GPS coordinates. The from-icloud command does something similar with the CSV files Apple includes, using them to recover creation dates and album structure. from-picasa reads .picasa.ini files to rebuild Picasa albums.

Server-side behaviour matters as much as parsing. The README lists duplicate detection, stacking of RAW+JPEG pairs and bursts, and the ability to pause Immich background jobs such as thumbnailing during an upload. That last one is a real operational choice: an upload saturates the server, and pausing its own jobs keeps the two from competing. The README also claims the tool has handled 100,000+ photos, which is a scale statement from the maintainer, not a measured benchmark.

## Installing immich-go and running a first upload

There is no package manager step in the README. The documented install is to download the pre-built binary for your platform from the GitHub releases page. On Linux and macOS that means making the file executable before you run it.

```bash
chmod +x immich-go
./immich-go --help
```

The help output lists the top-level commands. To push a plain folder of photos, the README gives this form:

```bash
immich-go upload from-folder --server=http://your-ip:2283 --api-key=your-api-key /path/to/your/photos
```

Replace the server address with your own Immich instance and the API key with one created in Immich. Port 2283 is the address used in the README example. For a Google Photos export, point the command at the ZIP files rather than an extracted tree:

```bash
immich-go upload from-google-photos --server=http://your-ip:2283 --api-key=your-api-key /path/to/takeout-*.zip
```

The glob is deliberate: Google splits large takeouts into numbered archives, and the README shows the wildcard form so all parts are consumed in one run. Expect album creation, metadata attachment and duplicate checks to appear in the command output as it proceeds.

## Banning junk files before they reach your library

A takeout is never only photos. It carries thumbnails, Synology indexing folders and macOS resource forks. immich-go filters these with the --ban-file flag, and the syntax distinguishes files from directories by the trailing slash: a pattern ending in / applies to directories, one without it applies to individual files. The README gives --ban-file .Spotlight-V100/ and --ban-file .DS_Store as the two examples.

Defaults already cover a fair amount: @eaDir/, @__thumb/, SYNOFILE_THUMB_*.*, Lightroom Catalog/, thumbnails/, .DS_Store, /._*, .Spotlight-V100/, .photostructure/ and Recently Deleted/. The docs/technical.md banned-files reference is where the full behaviour is described. This is the setting to check first when an upload produces entries you did not expect, because a pattern that should have matched a directory but lacks the trailing slash will not exclude it.

## The API permission change in v0.32.0

The most recent release, v0.32.0 on 2026-06-25, is titled Immich V3 compatibility and carries a breaking change. The ReplaceAsset API method has been removed. The asset.replace permission is no longer needed, and the release notes state that if your API key still includes it, the server ignores it. For asset duplication, the notes point to asset.copy instead.

This is a server-side contract change, not a flag rename, so it affects anyone whose API key was scoped for the old method. The practical consequence is that an existing key keeps working; the permission simply stops doing anything. The README marks the release as compatible with Immich V2 and V3, and the version history shows a jump from v0.31.0 in November 2025 to v0.32.0 in June 2026, so the V3 work landed in a single release rather than gradually. The repository's last push was on 2026-06-25, the same day as that release.

## Where immich-go is the wrong tool

The README is unusually direct about this: it labels the project an early version, not yet extensively tested, and asks you to keep a backup copy of your files. Take that at face value. This is a write path into a photo library you presumably care about, and the maintainer is telling you not to treat it as the only copy.

Three concrete cases argue against it. If you want a graphical interface, there is none; the repository layout shows a CLI and a terminal UI built on tview and tcell, not a desktop application, and the search data around immich-go gui, desktop, ios and android has no counterpart in the README. If you are moving a handful of files, the setup cost of creating an API key and locating the right binary outweighs the benefit. And if you need a documented rollback path, the README does not describe one: it covers uploading and archiving, and the archiving command writes assets out to a folder, but nothing in the documentation describes undoing an upload that landed incorrectly. Duplicate detection reduces the damage of a re-run, but it is not a rollback.

## immich-go against the official immich-CLI

The obvious alternative is the immich-CLI, which the project description names directly as the thing immich-go is an alternative to. The difference is not the destination, since both target the same Immich server API, but the runtime and the source handling. The official CLI is a Node.js package, so it needs a Node installation on whatever machine runs it. immich-go is a compiled Go binary, and the README makes the absence of NodeJS and Docker a headline feature.

The second difference is source coverage. immich-go ships dedicated commands for Google Photos takeouts, iCloud exports and Picasa libraries, each of which parses a different metadata format. If your library is already a clean folder tree with XMP sidecars, from-folder handles it and the distinction matters less. If it is a pile of takeout ZIPs with JSON sidecars, the parsing work is where the value is. The trade-off is the one the README admits: the official CLI is the reference implementation for a server the same team maintains, while immich-go tracks that server's API independently and had to absorb the V3 ReplaceAsset removal on its own schedule.

## Licence and the cost of staying current

immich-go is licensed under AGPL-3.0. That is a copyleft licence with a network clause, and it matters if you plan to modify the tool and expose it to users over a network rather than running it locally against your own server. For the ordinary case, downloading the binary and uploading your own photos, the licence imposes no practical obligation on your photo library. This is a description of the licence identifier, not legal advice; read LICENSE in the repository if your use is not the ordinary one.

Upgrade cost is tied to the Immich server, not to the tool's own release cadence. The V3 compatibility release shows what an upgrade looks like: a removed server API method, a permission that becomes a no-op, and a pointer to asset.copy for the affected use case. The version history shows releases at irregular intervals, with v0.30.0 and v0.31.0 a week apart in November 2025 and then a seven-month gap to v0.32.0. The repository is not archived, but the last push was on 2026-06-25, so if you depend on a fix for a newer Immich API change, check the releases page rather than assuming a patch is imminent.

## Conclusion

immich-go is for people who already run Immich and need to move a large existing library into it, especially a Google Photos takeout where albums, descriptions and locations live in sidecar JSON files. It is not for anyone who wants a GUI, a mobile app or a hosted service; there is no iOS or Android client and no desktop application. Before the first real run, verify that your Immich server is reachable at its API address, that the API key carries the permissions listed in docs/installation.md, and that you hold a separate backup of the source files, because the README asks you to keep one and the tool writes to your server rather than to your archive.

## FAQ

### What is immich-go?

It is an open-source command line tool that uploads large photo collections to a self-hosted Immich server. The README describes it as an alternative to the immich-CLI that does not require a Node.js installation.

### Can I import photos from Google Takeout into Immich with immich-go?

Yes. The from-google-photos command takes takeout ZIP files and matches each photo with its JSON metadata to preserve albums, descriptions and locations, as described in the README.

### How do I download and install immich-go?

The README says to download the pre-built binary for your system from the GitHub releases page. There is no package manager step documented, and the tool requires no Node.js or Docker.

### How do I use immich-go on Windows?

Windows binaries are published on the releases page, and the command syntax is the same as on other platforms. For a local folder, the README shows immich-go upload from-folder with the server address and API key.

### Is immich-go safe to run against my photo library?

The README labels the project an early version that has not been extensively tested and asks you to keep a backup copy of your files. It writes to your Immich server, and no rollback procedure is documented.

### Where does immich-go write its log file?

The README does not document a log file path. It links to docs/configuration.md for configuration options and environment variables, which is where logging behaviour would be described.

## Sources

- [Issues](https://github.com/simulot/immich-go/issues)
- [License: AGPL-3.0](https://github.com/simulot/immich-go/blob/main/LICENSE)
- [README](https://github.com/simulot/immich-go/blob/main/README.md)
- [Releases](https://github.com/simulot/immich-go/releases)
- [simulot/immich-go on GitHub](https://github.com/simulot/immich-go)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/simulot-immich-go