immich-go Documentation

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

6,121 stars Go Go 1 file · ~5,827 tokens #golang#google#immich#immich-cli#photos#takeout
RAW Doc

File: README.md

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

bash
# 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

Topic Description
Installation Detailed installation instructions for all platforms
Commands Complete command reference and options
Configuration Configuration options and environment variables
Examples Common use cases and practical examples
Best Practices Tips for optimal performance and reliability
Technical Details File processing, metadata handling, and advanced features
Upload Commands Overview How immich-go processes files from different sources
Release Notes Version history and release notes

✨ 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.

💡 Support the Project

🤝 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.

File: Readme.md

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

bash
# 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

Topic Description
Installation Detailed installation instructions for all platforms
Commands Complete command reference and options
Configuration Configuration options and environment variables
Examples Common use cases and practical examples
Best Practices Tips for optimal performance and reliability
Technical Details File processing, metadata handling, and advanced features
Upload Commands Overview How immich-go processes files from different sources
Release Notes Version history and release notes

✨ 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.

💡 Support the Project

🤝 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.

File: readme.md

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

bash
# 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

Topic Description
Installation Detailed installation instructions for all platforms
Commands Complete command reference and options
Configuration Configuration options and environment variables
Examples Common use cases and practical examples
Best Practices Tips for optimal performance and reliability
Technical Details File processing, metadata handling, and advanced features
Upload Commands Overview How immich-go processes files from different sources
Release Notes Version history and release notes

✨ 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.

💡 Support the Project

🤝 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.

File: docs/README.md

Immich-Go Documentation

Welcome to the complete documentation for Immich-Go, an open-source tool for uploading and managing photo collections with your self-hosted Immich server.

📖 Documentation Overview

This documentation is organized into several sections to help you get started quickly and master advanced features:

🚀 Getting Started

  • Installation - Complete installation guide for all platforms
  • Examples - Common use cases and practical examples
  • Configuration - Environment variables and configuration options

📝 Command Reference

📋 Best Practices & Advanced Topics

🔧 Specialized Topics

🎯 Quick Navigation by Use Case

New Users

  1. Start with Installation to set up Immich-Go
  2. Review Examples for your specific use case
  3. Check Best Practices for optimal performance

Google Photos Migration

Advanced Users

🛠 Common Commands Quick Reference

bash
# Upload from local folder
immich-go upload from-folder --server=SERVER --api-key=KEY /path/to/photos

# Upload Google Photos takeout
immich-go upload from-google-photos --server=SERVER --api-key=KEY /path/to/takeout.zip

# Archive from Immich server
immich-go archive from-immich --server=SERVER --api-key=KEY --write-to-folder=/archive

# Stack similar photos
immich-go stack --server=SERVER --api-key=KEY

📚 Documentation Structure

text
docs/
├── README.md                    # This file - documentation hub
├── installation.md              # Installation guide
├── configuration.md             # Configuration options
├── environment.md              # Environment setup
├── examples.md                 # Practical examples
├── best-practices.md           # Performance and reliability tips
├── technical.md                # Technical details and internals
├── commands/                   # Command reference
│   ├── README.md              # Command overview
│   ├── upload.md              # Upload commands
│   ├── archive.md             # Archive commands
│   └── stack.md               # Stack commands
├── concurrency/               # Performance optimization
│   ├── README.md             # Concurrency overview
│   └── multi-threading.md    # Threading details
└── misc/                      # Additional guides
    ├── README.md             # Miscellaneous topics index
    ├── google-takeout.md     # Google Photos migration
    ├── motivation.md         # Project background
    └── troubleshooting.md    # Common issues and solutions

🆘 Getting Help

🤝 Contributing to Documentation

Documentation improvements are always welcome! See our contributing guidelines for details on:

  • Fixing typos or errors
  • Adding examples
  • Improving clarity
  • Adding new sections

📄 License

This documentation is part of the Immich-Go project and is licensed under the same terms as specified in the LICENSE file.

Ready to get started? Begin with the Installation Guide or jump to Examples for your specific use case.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#golang Browse golang catalog → #google Browse google catalog → #immich Browse immich catalog → #immich-cli Browse immich-cli catalog → #photos Browse photos catalog → #takeout Browse takeout catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →