simulot/immich-go

Immich-Go: Upload Your Photos to Your Immich Server

Immich-Go is an open-source tool designed to streamline uploading large photo collections to your self-hosted Immich server.

✅ Compatible with Immich V2 and V3
⚠️ This is an early version, not yet extensively tested
⚠️ Keep a backup copy of your files for safety

🌟 Key Features

• Immich V3 Ready: Full compatibility with Immich V2 and V3
• Simple Installation: No NodeJS or Docker required
• Multiple Sources: Upload from Google Photos Takeouts, iCloud, local folders, ZIP archives, and other Immich servers
• Large Collections: Successfully handles 100,000+ photos
• Smart Management: Duplicate detection, burst photo stacking, RAW+JPEG handling
• Cross-Platform: Available for Windows, macOS, Linux, and FreeBSD

🚀 Quick Start

1. Install Immich-Go

Download the pre-built binary for your system from the GitHub releases page.

2. Basic Usage

# Upload photos from a local folder
immich-go upload from-folder --server=http://your-ip:2283 --api-key=your-api-key /path/to/your/photos

# Upload Google Photos takeout
immich-go upload from-google-photos --server=http://your-ip:2283 --api-key=your-api-key /path/to/takeout-*.zip

# Archive photos from Immich server
immich-go archive from-immich --from-server=http://your-ip:2283 --from-api-key=your-api-key --write-to-folder=/path/to/archive

3. Requirements

• A running Immich server with API access
• API key with appropriate permissions (see full list)

⚠️ Breaking Change (v0.32.0): The ReplaceAsset API method has been removed. The asset.replace permission is no longer needed. If your API key includes it, it will be ignored by the server. Use asset.copy instead for asset duplication needs.

🙈 Skip System Files

• Use --ban-file to exclude junk artifacts. Patterns ending with / apply to directories (for example, --ban-file .Spotlight-V100/), while patterns without the trailing slash apply to individual files (for example, --ban-file .DS_Store).
• Immich-Go ships with sensible defaults that already skip common clutter such as @eaDir/, @__thumb/, SYNOFILE_THUMB_*.*, Lightroom Catalog/, thumbnails/, .DS_Store, /._*, .Spotlight-V100/, .photostructure/, and Recently Deleted/.
• Add additional patterns as needed to keep uploads focused on real photos. See the banned files reference for details.

📚 Documentation

✨ How immich-go Works

immich-go offers a versatile set of commands to handle your photo and video uploads. Whether you're uploading from a simple folder, migrating from a Google Photos Takeout, or transferring assets between Immich servers, the tool provides intelligent features to preserve your metadata and organization.

Here's a brief overview of the main upload commands:

• from-folder: The basic command for uploading from any local folder. It can create albums from your directory structure and read XMP sidecar files.
• from-google-photos: A powerful command to migrate from a Google Photos Takeout. It intelligently matches photos with their JSON metadata to preserve albums, descriptions, and locations.
• from-immich: A server-to-server migration tool that allows you to copy assets between two Immich instances with fine-grained filtering.
• from-picasa: A specialized version of from-folder that automatically reads .picasa.ini files to restore your Picasa album organization.
• from-icloud: Another specialized command that handles the complexity of an iCloud Photos takeout, correctly identifying creation dates and album structures from the included CSV files.

Leveraging Immich's Features

immich-go is more than just an uploader; it intelligently interacts with the Immich server to preserve your library's structure:

• Albums and Tags: Automatically creates albums and tags on the server to match your source organization.
• Stacking: Groups related images, like RAW+JPEG pairs or photo bursts, into stacks.
• Duplicate Detection: Avoids re-uploading files that already exist on the server.
• Efficient Uploads: Can pause Immich's background jobs (like thumbnailing) during an upload for better performance.

For a detailed explanation of how each upload command works, please see the Upload Commands Overview.

🎯 Popular Use Cases

• Google Photos Migration: Complete guide
• iCloud Import: Step-by-step instructions
• Server Migration: Transfer between Immich instances
• Bulk Organization: Stacking and tagging strategies

💡 Support the Project

• GitHub Sponsor
• PayPal Donation

🤝 Contributing

Contributions are welcome! Please see our contributing guidelines for details.

📄 License

This project is licensed under the terms specified in the LICENSE file.

Need help? Check our documentation or open an issue on GitHub.