Release Notes - v0.32.0 - Immich V3 compatibility

Release Notes - v0.32.0

This release brings full compatibility with Immich V3.0.0. All upload, album, and server
communication paths have been updated to work with the new API while maintaining backward
compatibility with Immich V2.

A big thank you to bwees who has done the very neat work for addressing changes:

✨ New Features

• Immich V3 support – Full compatibility with Immich V3.0.0. The tool now detects the
  server version and adapts its behavior accordingly, ensuring smooth operation regardless
  of which version you're running.
• Server version detection – immich-go now reads and exposes the server version at
  startup, enabling version-aware API calls.

🚀 Improvements

• Album contents via search – Album asset retrieval now uses the paginated
  POST /api/search/metadata endpoint instead of relying on GET /api/albums/{id} to
  return assets. This works with both Immich V2 and V3 and is more reliable for large
  albums.
• Error handling overhaul – Server error messages are now parsed according to the
  server version (Zod-based errors for V3, legacy format for V2), providing clearer and
  more actionable error output.

🔧 Internal Changes

• Asset upload field changes – Removed deviceId and deviceAssetId from the upload
  payload (dropped in Immich V3's AssetMediaCreateDto). These fields are silently
  ignored by V2, so this change is safe across versions.

• Duration field handling – The duration field has been updated to use "0" as a
  plain string value, which is accepted by both Immich V2 and V3.

• Removed deprecated replaceAsset – The ReplaceAsset method and its associated
  asset.replace permission have been removed entirely. Use CopyAsset instead.

• Error processing moved to immich/error.go – All server error parsing logic is now
  centralized with a serverError interface and separate serverErrorV2/serverErrorV3
  implementations.

• Album contents E2E test – Added Test_GetImmichAlbums to verify that album uploads
  and duplicate detection work correctly with the new search-based album retrieval.

Changelog

• 6bbcad6 Merge pull request #1227 from simulot/dependabot/github_actions/actions/setup-go-6
• eaf6d44 Merge pull request #1228 from simulot/dependabot/github_actions/actions/upload-artifact-5
• 3fe9218 Merge pull request #1229 from simulot/dependabot/github_actions/actions/checkout-6
• 720fd5a Merge pull request #1230 from simulot/dependabot/github_actions/actions/setup-node-6
• 2e5607a Merge pull request #1231 from simulot/dependabot/github_actions/actions/github-script-8
• d274f81 Merge pull request #1260 from rob518183:patch-1
• cc928ed Merge pull request #1300 from marianwolf/main
• e6b8933 Merge pull request #1377 from bwees:fix/v3
• 3e5ee70 Update archive.md
• 6cfb85f chore(deps): bump actions/checkout from 4 to 6
• d43f6d1 chore(deps): bump actions/github-script from 7 to 8
• dd52877 chore(deps): bump actions/setup-go from 5 to 6
• 2cdd446 chore(deps): bump actions/setup-node from 4 to 6
• 59e781e chore(deps): bump actions/upload-artifact from 4 to 5
• f7d19fc doc: update readme for v0.32.0 with Immich V3 support
• 51e2032 feat: add release notes for v0.32.0 with Immich V3 compatibility and improvements
• 5ca6b5a fix: album upload
• 18196f9 fix: immich v3 support
• d717789 update archive bash command in readme

v0.31.0

Release Notes - v0.31.0

This release focuses on richer visibility while uploading assets and a major refresh of the CI/CD system that keeps Immich Go healthy across every platform.

✨ New Features

• Live terminal tracking – The TUI now exposes separate discovery and processing zones, FileArchived counters, and per-asset size tracking so you can immediately tell what is being scanned, uploaded, or archived.
• Better metadata insight – FileProcessor records processed assets (including metadata-only updates) and publishes dedicated events, yielding more accurate progress reporting and easier troubleshooting.

🚀 Improvements

• Globbing resilience – Folder traversal keeps going when the filesystem throws access errors and now surfaces clearer documentation about supported patterns.
• Upload ergonomics – Standardized error-handling flags across upload commands and improved UI layout by right-aligning size columns, making long-running jobs easier to read.

🐛 Bug Fixes

• Album flag conflict – --folder-as-album=NONE no longer clashes with --into-album, so you can explicitly skip derived album names while still targeting a destination album.

🔧 Internal Changes

• Revamped CI/CD – Introduced a two-stage fast-feedback + secure E2E workflow, nightly Immich E2E runs, fork-safe triggering, and far more robust helper scripts (doc-only detection, jq fixes, empty-diff handling, standardized formatting).
• Safer E2E workflow – External contributors now rely on an approval gate (or /run-e2e comment), and the workflow dispatch code was hardened with better payload validation, environment routing, and completion reporting.
• Broader coverage – Added an album-upload E2E test, refreshed dependency stack (tcell v2.11.0, crypto v0.45.0), and removed legacy journal/reporting structures in favor of a unified FileProcessor + new file-event codes.

New Contributors

• @mcastorina made their first contribution in #1189
• @niieani made their first contribution in #1146
• @domodwyer made their first contribution in #1177
• @aplathan made their first contribution in #1176

Full Changelog: v0.30.0...v0.31.0

v0.30.0

Release Notes for v0.30.0

We're excited to announce the next major release of immich-go, bringing significant improvements to testing infrastructure, enhanced filtering capabilities, and better stability across the board. This release includes comprehensive end-to-end testing, new asset filtering options, and important bug fixes that improve the overall user experience.

✨ New Features

• Enhanced Asset Filtering: Added support for filtering assets by city, country, state, camera make, model, and tags in the from-immich command
• Album and People Filtering: New options to filter assets by specific albums, people, and exclude partner's photos
• Search Suggestions: New GetSearchSuggestions method for improved search functionality
• Copy Asset Feature: Introduced CopyAsset method for asset duplication (replacing deprecated ReplaceAsset)

🚀 Improvements

• Unified Asset Tracking: Implemented a new FileProcessor system for consistent asset tracking and event logging across all adapters
• E2E Testing Framework: Added comprehensive end-to-end tests for upload and archive commands with automated Immich server setup
• Adapter Migration: Migrated folder, Google Photos, and from-immich adapters to the new FileProcessor design for better performance and consistency
• Error Handling: Improved error handling in multipart uploads and server communications
• CLI Consistency: Standardized flag naming and added persistent flag support for better subcommand inheritance
• Configuration: Enhanced configuration file support with better serialization and validation
• Documentation: Updated command documentation with comprehensive examples and improved readability

🐛 Bug Fixes

• Race Condition Fix: Resolved race condition in uploadAsset function that could cause upload failures
• E2E Test Stability: Fixed various E2E test issues including server readiness checks, Windows compatibility, and user provisioning
• API Compatibility: Updated API calls to use newer endpoints and improved error handling
• Date Range Validation: Added validation to ensure date ranges are logically consistent
• File Extension Handling: Fixed MP4 extension handling and improved file type detection
• CI/CD Improvements: Enhanced workflow reliability and reduced false positives in automated checks

💥 Breaking Changes

• Flag Renaming: Renamed --server-errors flag to --on-errors for consistency
• API Changes: Updated replaceAsset method to use assets/copy endpoint instead of direct replacement
• Configuration Structure: Some internal configuration structures have changed for better serialization

🔧 Internal Changes

• Code Refactoring: Extensive refactoring to improve code maintainability and remove technical debt
• Dependency Updates: Updated Go dependencies and CI/CD tools to latest versions
• Test Infrastructure: Added E2E test tasks to pre-commit checks and improved test coverage
• Documentation Generation: Enhanced automated documentation generation and release notes process
• CI/CD Optimization: Streamlined workflows with conditional E2E testing and improved branch validation

What's Changed

• v0.29.0 by @simulot in #1164
• chore(deps): bump actions/setup-go from 5 to 6 by @dependabot[bot] in #1094
• chore(deps): bump actions/checkout from 4 to 5 by @dependabot[bot] in #1095
• feature: improve documentation and developer experience by @simulot in #1171
• chore(deps): bump golangci/golangci-lint-action from 8 to 9 by @dependabot[bot] in #1170
• chore(deps): bump actions/github-script from 7 to 8 by @dependabot[bot] in #1169
• feature: unified asset tracking and event logging system by @simulot in #1179
• chore: update Go dependencies by @simulot in #1180
• feature/fix CLI flag inconsistencies in documentation by @simulot in #1181
• feature: add e2e tests for from-folder by @simulot in #1183
• docs: add release notes for v0.30.0 with new features, improvements, bug fixes, breaking changes, and internal updates by @simulot in #1184
• release: v0.30.0 by @simulot in #1185

Full Changelog: v0.29.0...v0.30.0

v0.29.0

Release Notes - v0.29.0

This release brings powerful new filtering capabilities for the from-immich command and configuration file support, making it easier to manage complex migration scenarios.

✨ New Features

• Advanced asset filtering for from-immich - Filter your Immich library with precision using:

  • --from-people - Filter by people/faces in photos
  • --from-tag - Filter by tags
  • --from-album, --from-no-album - Filter by albums, including assets not in any album
  • --from-city, --from-country, --from-state - Geographic filtering
  • --from-make, --from-model - Camera make and model filtering with validation
  • --from-archived, --from-trashed, --from-favorite - Filter by asset state
  • --from-minimal-rating - Filter by minimum rating
  • --from-partners - Exclude partner's shared photos
  • --from-date-range - Filter by a date range (dates, date, year)
  • --from-include-extensions, --from-exclude-extensions - Include/exclude file extensions (e.g., include .jpg but exclude .bmp)
  • --from-include-type - Select only videos or only photos

  Example:

  immich-go from-immich [server parameters] --from-people="John" --from-date=2024 --from-favorite

• Configuration file support - Create YAML/TOML configuration files to manage settings across projects
  Configuration values can come from files, environment variables, or command-line flags, with clear logging of which source is used.
  Check the documentation for supported formats and usage at /docs/configuration.md.

🚀 Improvements

• Renamed --server-errors to --on-errors - More consistent flag naming across commands for error handling behavior

• Better upload logging - Upload events now show asset details instead of just filenames, making it easier to track progress during large migrations

• Enhanced configuration visibility - The application now logs:

  • Which configuration file is being used (if any)
  • Where each setting comes from (file, environment, or command-line)
  • All active flags and parameters at startup for easier debugging

• Streamlined CLI structure:

  • Concurrency settings (e.g., --concurrent-upload) now available from the root command
  • Clearer separation between upload, archive, and from-* commands
  • Simplified from-folder command usage

• Date range validation - Automatically prevents invalid date ranges where "before" is after "after"

• Comprehensive documentation - New guides for installation, usage examples, migration scenarios, and performance tuning

💥 Breaking Changes

• Asset copy API change - If you use the API directly: ReplaceAsset method is deprecated in favor of CopyAsset, which uses the assets/copy endpoint

• API key permissions update - API keys must now include asset.copy and asset.delete permissions in addition to previously required permissions. Please update your API keys accordingly.

🔧 Internal Changes

• Complete E2E testing infrastructure - Comprehensive automated testing with Linux and Windows clients, ensuring reliability across platforms

• Improved CI/CD - Smarter test execution (skips E2E tests for documentation-only changes), updated GitHub Actions, unified workflow

• Code quality - Updated to Immich API 2.0.0, better code organization, enhanced debugging capabilities

• Developer tools - VS Code tasks for common operations, automated release workflow, development branch now named develop

What's Changed

• Update branch naming and validation rules in CONTRIBUTING.md by @simulot in #1075
• Update branch naming and validation rules in CONTRIBUTING.md by @simulot in #1076
• Fix visibility handling for archived Google Photos uploads by @simulot in #1078
• Fixes completion by @simulot in #1080
• Enhance asset filtering and retrieval features by @simulot in #1081
• Implement httptrace package for enhanced request/response logging by @simulot in #1082
• docs: Comprehensive documentation restructuring and improvement by @simulot in #1084
• Add comprehensive documentation for Immich-Go by @simulot in #1085
• refactor: makes the linter happy by @simulot in #1086
• feat: add vstask for runing linter and prepare PR by @simulot in #1087
• Add Immich API Monitor Script to check OpenAPI specifications by @simulot in #1088
• feat: add interactive script for deleting local Git branches by @simulot in #1089
• refactor: improve concurrency handling in dumpReader and update trace logging methods by @simulot in #1090
• Refactor configuration management and enhance documentation by @simulot in #1097
• feat(scripts): remove deprecated pre-release scripts and update publish script for improved versioning by @simulot in #1098
• Feature/from-immich-options by @simulot in #1100
• Feature/global-errors-flag by @simulot in #1103
• reafactoring cobre CLI management by @simulot in #1117
• Feature/e2etests by @simulot in #1127
• Feature/move_test_immich by @simulot in #1154
• Feature/implement api change by @simulot in #1162
• Feature/release-note-generation by @simulot in #1163

Full Changelog: v0.28.0...v0.29.0

v0.29.4-dev-56e4e32

CI Pipeline Upgrade: Pre-Merge Cross-Platform & API Regression Testing

A more robust CI workflow is now enforced for all Pull Requests. This pipeline executes the complete test suite on both Linux and Windows using the latest published immich-server to proactively catch platform-specific errors and regressions stemming from upstream API changes.

Changelog

• 56e4e32 Merge pull request #1154 from simulot:feature/move_test_immich
• 53e33d3 Refactor e2e scripts and configuration paths
• 88cea87 fix: .gitignore
• f7bb594 fix: update CI paths and golangci-lint configuration for improved test coverage

v0.29.2-dev-3d89bdd more options for `from-immich`

more filters from the command from-immich:

Flags:
      --from-albums strings                     Get assets only from those albums, can be used multiple times
      --from-api-key string                     API Key
      --from-api-trace                          Enable trace of api calls
      --from-archived                           Get only archived assets
      --from-city string                        Get only assets from this city
      --from-client-timeout duration            Set server calls timeout (default 20m0s)
      --from-country string                     Get only assets from this country
      --from-date-range date-range              Only import photos taken within the specified date range (default unset)
      --from-exclude-extensions ExtensionList   Comma-separated list of extension to exclude. (e.g. .gif,.PM) (default: none)
      --from-favorite                           Get only favorite assets
      --from-include-extensions ExtensionList   Comma-separated list of extension to include. (e.g. .jpg,.heic) (default: all)
      --from-include-type IncludeType           Single file type to include. (VIDEO or IMAGE) (default: all)
      --from-make string                        Get only assets with this make
      --from-minimal-rating int                 Get only assets with a rating greater or equal to this value
      --from-model string                       Get only assets with this model
      --from-no-album                           Get only assets that are not in any album
      --from-partners                           Get partner's assets as well
      --from-people strings                     Get assets only with those people, can be used multiple times
      --from-server string                      Immich server address (example http://your-ip:2283 or https://your-domain)
      --from-skip-verify-ssl                    Skip SSL verification
      --from-state string                       Get only assets from this state
      --from-tags strings                       Get assets only with those tags, can be used multiple times
      --from-trash                              Get only trashed assets
  -h, --help                                    help for from-immich

and from the previous pre-releases:

• rewriting of the readme
• configuration files
• Environment variables

What's Changed

• Update branch naming and validation rules in CONTRIBUTING.md by @simulot in #1075
• Fix visibility handling for archived Google Photos uploads by @simulot in #1078
• Fixes completion by @simulot in #1080
• Enhance asset filtering and retrieval features by @simulot in #1081
• Implement httptrace package for enhanced request/response logging by @simulot in #1082
• docs: Comprehensive documentation restructuring and improvement by @simulot in #1084
• Add comprehensive documentation for Immich-Go by @simulot in #1085
• refactor: makes the linter happy by @simulot in #1086
• feat: add vstask for runing linter and prepare PR by @simulot in #1087
• Add Immich API Monitor Script to check OpenAPI specifications by @simulot in #1088
• feat: add interactive script for deleting local Git branches by @simulot in #1089
• refactor: improve concurrency handling in dumpReader and update trace logging methods by @simulot in #1090
• Refactor configuration management and enhance documentation by @simulot in #1097
• feat(scripts): remove deprecated pre-release scripts and update publish script for improved versioning by @simulot in #1098
• Feature/from-immich-options by @simulot in #1100

Full Changelog: v0.28.0...v0.29.2-dev-3d89bdd

v0.29.2-8144339 configuration file

New features

Readme and documentation rewritten

better management of configuration files.
The existing configuration files must be rewritten.
YAML, TOML and JSON formats

can use environment variables

Changelog since v0.28.0

What's Changed

• Update branch naming and validation rules in CONTRIBUTING.md by @simulot in #1075
• Fix visibility handling for archived Google Photos uploads by @simulot in #1078
• Fixes completion by @simulot in #1080
• Enhance asset filtering and retrieval features by @simulot in #1081
• Implement httptrace package for enhanced request/response logging by @simulot in #1082
• docs: Comprehensive documentation restructuring and improvement by @simulot in #1084
• Add comprehensive documentation for Immich-Go by @simulot in #1085
• refactor: makes the linter happy by @simulot in #1086
• feat: add vstask for runing linter and prepare PR by @simulot in #1087
• Add Immich API Monitor Script to check OpenAPI specifications by @simulot in #1088
• feat: add interactive script for deleting local Git branches by @simulot in #1089
• refactor: improve concurrency handling in dumpReader and update trace logging methods by @simulot in #1090
• Refactor configuration management and enhance documentation by @simulot in #1097
• feat(scripts): remove deprecated pre-release scripts and update publish script for improved versioning by @simulot in #1098

Full Changelog: v0.28.0...v0.29.2-8144339

v0.28.0 Concurrent Uploads

Parallel Uploads

On the immich-go side, upload operations are primarily limited by I/O, whether reading takeouts and files or sending files to the server. To improve upload throughput, @jonathan-teamstatus proposed enabling parallel uploads.
On my machine, the best performance is achieved when the number of parallel uploads matches the number of cores, resulting in a 2.5x performance gain. I set the default value for the parameter --concurrent-uploads with the number of available cores.

Server jobs are paused during the upload (as before), allowing the upload to run at full speed. Once complete, server jobs resume, and the heavy lifting begins (thumbnails, machine learning, video encoding, etc.).

Thank you to the new contributors:

• @pmorch made their first contribution in #1006
• @Qhilm made their first contribution in #1048
• @paultyng made their first contribution in #1045
• @jonathan-teamstatus made their first contribution in #993

Noteworthy changes

Fixed: job pausing / resuming:
Only the jobs "thumbnailGeneration", "metadataExtraction", "videoConversion", "faceDetection", "smartSearch" are paused. Those jobs are resumed at the end of the run.

Fixed: Windows #1010:
The windows folders are now correctly parsed

Fixed: Album creation when uploading from an immich server

What's Changed

• Simulot/issue1055 by @simulot in #1059
• add API key permissions by @Qhilm in #1048
• make func (t *ImmichExifTime) UnmarshalJSON support hundreths and tenths of seconds too by @pmorch in #1006
• Use unix style paths internally and test on windows by @paultyng in #1045
• Add concurrent uploads support by @jonathan-teamstatus in #993
• docs: add contributing guidelines to improve collaboration by @simulot in #1063
• feat: add workflow to validate branch naming conventions and target branches by @simulot in #1064
• Feature/documentation-on-concurrency by @simulot in #1066
• Bugfix/from-immich-album by @simulot in #1070
• Fix issues with image archiving, job pausing, and asset uploads by @simulot in #1072
• chore(deps): bump github.com/spf13/pflag from 1.0.6 to 1.0.9 by @dependabot[bot] in #1044
• chore(deps): bump github.com/spf13/pflag from 1.0.9 to 1.0.10 by @dependabot[bot] in #1052
• chore(deps): bump github.com/rivo/tview from 0.0.0-20241227133733-17b7edb88c57 to 0.42.0 by @dependabot[bot] in #1043
• chore(deps): bump actions/checkout from 4 to 5 by @dependabot[bot] in #1039
• chore(deps): bump github.com/gdamore/tcell/v2 from 2.8.1 to 2.9.0 by @dependabot[bot] in #1040
• chore(deps): bump github.com/go-viper/mapstructure/v2 from 2.2.1 to 2.4.0 in the go_modules group across 1 directory by @dependabot[bot] in #1035
• chore(deps): bump github.com/navidys/tvxwidgets from 0.11.0 to 0.11.3 by @dependabot[bot] in #1028
• chore(deps): bump golang.org/x/sync from 0.15.0 to 0.16.0 by @dependabot[bot] in #1009
• chore(deps): bump golangci/golangci-lint-action from 7 to 8 by @dependabot[bot] in #921
• chore(deps): bump actions/setup-go from 5 to 6 by @dependabot[bot] in #1051
• chore(deps): bump github.com/samber/slog-multi from 1.4.1 to 1.5.0 by @dependabot[bot] in #1054

Full Changelog: v0.27.0...v0.28.0

v0.27.0 Faster uploads when photos are located on a nework folder

Faster

PaulSonOfLars has significantly improved the performance of immich-go when the source of photos is located on a network folder. In his environment, the performance boost is remarkable, going from uploading one picture every 2 seconds to 25 pictures per second: a near 50x increase.

A heartfelt thank you to PaulSonOfLars for this incredible contribution.

What's Changed

• Fix nix flakes command in readme by @Migelo in #952
• Update readme.md - Fix asset filenames docs from amd64 to x86_64 by @adrydale in #975
• Feat: Implement new virtual glob filesystem by @PaulSonOfLars in #971

New Contributors

We are thrilled to welcome new contributors to the project:

• @Migelo made their first contribution in #952
• @adrydale made their first contribution in #975
• @PaulSonOfLars made their first contribution in #971

A big thank you to all contributors for their hard work and dedication to improving immich-go. Your efforts make this project better for everyone!

---

Full Changelog: v0.26.3...v0.27.0

v0.26.3 Fix archive command

What's Changed

• chore(deps): bump golang.org/x/sync from 0.13.0 to 0.14.0 by @dependabot in #935
• Fixes #942: archive command fails by @simulot in #947
• Added build instructions for Termux to readme.md by @Syntoxr in #939

New Contributors

• @Syntoxr made their first contribution in #939

Full Changelog: v0.26.2...v0.26.3