## 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](https://github.com/simulot/immich-go/releases). ### 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](docs/installation.md#api-permissions)) > ⚠️ **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](docs/technical.md#banned-files) for details. ## 📚 Documentation | Topic | Description | |-------|-------------| | [Installation](docs/installation.md) | Detailed installation instructions for all platforms | | [Commands](docs/commands/) | Complete command reference and options | | [Configuration](docs/configuration.md) | Configuration options and environment variables | | [Examples](docs/examples.md) | Common use cases and practical examples | | [Best Practices](docs/best-practices.md) | Tips for optimal performance and reliability | | [Technical Details](docs/technical.md) | File processing, metadata handling, and advanced features | | [Upload Commands Overview](docs/upload-commands-overview.md) | How `immich-go` processes files from different sources | | [Release Notes](docs/releases/) | 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](docs/upload-commands-overview.md). ## 🎯 Popular Use Cases - **Google Photos Migration**: [Complete guide](docs/best-practices.md#google-photos-migration) - **iCloud Import**: [Step-by-step instructions](docs/examples.md#icloud-import) - **Server Migration**: [Transfer between Immich instances](docs/examples.md#server-migration) - **Bulk Organization**: [Stacking and tagging strategies](docs/best-practices.md#organization-strategies) ## 💡 Support the Project - [GitHub Sponsor](https://github.com/sponsors/simulot) - [PayPal Donation](https://www.paypal.com/donate/?hosted_button_id=VGU2SQE88T2T4) ## 🤝 Contributing Contributions are welcome! Please see our [contributing guidelines](CONTRIBUTING.md) for details. ## 📄 License This project is licensed under the terms specified in the [LICENSE](LICENSE) file. --- **Need help?** Check our [documentation](docs/) 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](https://github.com/simulot/immich-go/releases). ### 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](docs/installation.md#api-permissions)) > ⚠️ **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](docs/technical.md#banned-files) for details. ## 📚 Documentation | Topic | Description | |-------|-------------| | [Installation](docs/installation.md) | Detailed installation instructions for all platforms | | [Commands](docs/commands/) | Complete command reference and options | | [Configuration](docs/configuration.md) | Configuration options and environment variables | | [Examples](docs/examples.md) | Common use cases and practical examples | | [Best Practices](docs/best-practices.md) | Tips for optimal performance and reliability | | [Technical Details](docs/technical.md) | File processing, metadata handling, and advanced features | | [Upload Commands Overview](docs/upload-commands-overview.md) | How `immich-go` processes files from different sources | | [Release Notes](docs/releases/) | 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](docs/upload-commands-overview.md). ## 🎯 Popular Use Cases - **Google Photos Migration**: [Complete guide](docs/best-practices.md#google-photos-migration) - **iCloud Import**: [Step-by-step instructions](docs/examples.md#icloud-import) - **Server Migration**: [Transfer between Immich instances](docs/examples.md#server-migration) - **Bulk Organization**: [Stacking and tagging strategies](docs/best-practices.md#organization-strategies) ## 💡 Support the Project - [GitHub Sponsor](https://github.com/sponsors/simulot) - [PayPal Donation](https://www.paypal.com/donate/?hosted_button_id=VGU2SQE88T2T4) ## 🤝 Contributing Contributions are welcome! Please see our [contributing guidelines](CONTRIBUTING.md) for details. ## 📄 License This project is licensed under the terms specified in the [LICENSE](LICENSE) file. --- **Need help?** Check our [documentation](docs/) 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](https://github.com/simulot/immich-go/releases). ### 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](docs/installation.md#api-permissions)) > ⚠️ **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](docs/technical.md#banned-files) for details. ## 📚 Documentation | Topic | Description | |-------|-------------| | [Installation](docs/installation.md) | Detailed installation instructions for all platforms | | [Commands](docs/commands/) | Complete command reference and options | | [Configuration](docs/configuration.md) | Configuration options and environment variables | | [Examples](docs/examples.md) | Common use cases and practical examples | | [Best Practices](docs/best-practices.md) | Tips for optimal performance and reliability | | [Technical Details](docs/technical.md) | File processing, metadata handling, and advanced features | | [Upload Commands Overview](docs/upload-commands-overview.md) | How `immich-go` processes files from different sources | | [Release Notes](docs/releases/) | 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](docs/upload-commands-overview.md). ## 🎯 Popular Use Cases - **Google Photos Migration**: [Complete guide](docs/best-practices.md#google-photos-migration) - **iCloud Import**: [Step-by-step instructions](docs/examples.md#icloud-import) - **Server Migration**: [Transfer between Immich instances](docs/examples.md#server-migration) - **Bulk Organization**: [Stacking and tagging strategies](docs/best-practices.md#organization-strategies) ## 💡 Support the Project - [GitHub Sponsor](https://github.com/sponsors/simulot) - [PayPal Donation](https://www.paypal.com/donate/?hosted_button_id=VGU2SQE88T2T4) ## 🤝 Contributing Contributions are welcome! Please see our [contributing guidelines](CONTRIBUTING.md) for details. ## 📄 License This project is licensed under the terms specified in the [LICENSE](LICENSE) file. --- **Need help?** Check our [documentation](docs/) 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**](installation.md) - Complete installation guide for all platforms - [**Examples**](examples.md) - Common use cases and practical examples - [**Configuration**](configuration.md) - Environment variables and configuration options ### 📝 Command Reference - [**Commands Overview**](commands/README.md) - Complete command structure and global options - [**Upload Commands**](commands/upload.md) - Detailed upload command documentation - [**Archive Commands**](commands/archive.md) - Export and archival operations - [**Stack Commands**](commands/stack.md) - Photo organization and stacking ### 📋 Best Practices & Advanced Topics - [**Best Practices**](best-practices.md) - Performance tips and optimization strategies - [**Technical Details**](technical.md) - File processing, metadata handling, and internals - [**Environment Setup**](environment.md) - Advanced environment configuration ### 🔧 Specialized Topics - [**Concurrency**](concurrency/) - Multi-threading and performance optimization - [**Miscellaneous**](misc/) - Additional guides and troubleshooting ## 🎯 Quick Navigation by Use Case ### New Users 1. Start with [Installation](installation.md) to set up Immich-Go 2. Review [Examples](examples.md) for your specific use case 3. Check [Best Practices](best-practices.md) for optimal performance ### Google Photos Migration - [Google Photos Takeout Guide](misc/google-takeout.md) - [Migration Best Practices](best-practices.md#google-photos-migration) - [Upload from Google Photos](commands/upload.md#from-google-photos) ### Advanced Users - [Technical Details](technical.md) for deep dive into functionality - [Configuration](configuration.md) for advanced customization - [Concurrency](concurrency/) for performance optimization ## 🛠 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 ``` 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 - **Documentation Issues**: Something unclear? [Open an issue](https://github.com/simulot/immich-go/issues) - **Bug Reports**: Found a problem? [Report it](https://github.com/simulot/immich-go/issues) - **Feature Requests**: Have an idea? [Share it](https://github.com/simulot/immich-go/discussions) - **Debug Information**: Need to send logs? See [how to send debug data](misc/how-to-send-debug-data.md) ## 🤝 Contributing to Documentation Documentation improvements are always welcome! See our [contributing guidelines](../CONTRIBUTING.md) 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](../LICENSE) file. --- **Ready to get started?** Begin with the [Installation Guide](installation.md) or jump to [Examples](examples.md) for your specific use case.