ZimaOS에 표시된 Immich 버전이 업스트림 Immich 릴리스보다 오래되었고 App Store에 업데이트 버튼이 제공되지 않는 경우, 컨테이너를 수동으로 업데이트할 방법이 있지만 정확한 방법은 설치한 ZimaOS Immich 패키지에 따라 다릅니다. 2025년 12월 IceWhale Community 스레드에서는 BigBear Immich 패키지의 간단한 이미지 태그 변경이 확인되었지만, 이후 답변에서는 동일한 방법이 다른 모든 Immich 패키지를 안정적으로 업데이트하지는 않는 것으로 나타났습니다.
커뮤니티 방법은 앱 설정을 열고 다음 항목만 변경하는 것이었습니다. immich-server 및 immich-machine-learning 이미지 태그를 대상 릴리스로 변경하고 데이터베이스 및 Redis 탭은 그대로 두는 방식이었습니다. 원 게시자는 업데이트가 원활하게 진행되었다고 확인했으며, 이후 다른 BigBear 사용자는 v2.3.1에서 v2.4.1로 성공적으로 업데이트했습니다. 그러나 현재 Immich 문서에서는 관리자가 릴리스 노트를 읽고, 데이터베이스를 백업하며, 업그레이드 전에 Compose 및 데이터베이스 변경 사항을 고려해야 한다고 안내합니다. 따라서 태그를 수동으로 변경하는 방법을 누구에게나 “항상 안전한” 업데이트 버튼처럼 취급해서는 안 됩니다.
먼저 설치한 Immich 패키지를 확인하세요
해당 스레드에는 최소 두 가지 배포 경로가 있습니다.
- BigBear Immich: 여러 사용자가 ZimaOS에서 이미지 태그를 수정하자 업데이트가 성공적으로 실행되었다고 보고했습니다.
- 기본/비BigBear 패키지: 이후 한 사용자는 서버와 머신러닝 버전을 수동으로 변경하려고 시도했음에도 v2.1.0에서 벗어나지 못했다고 보고했습니다.
ZimaOS에서 Immich 앱 설정을 열고, 변경하기 전에 현재 이미지 이름, 태그, 볼륨 매핑, 데이터베이스 이미지 및 환경 변수를 기록해 두세요. BigBear 정의용으로 작성된 지침이 다른 App Store 템플릿에도 적용된다고 가정하지 마세요.
커뮤니티에서 효과가 있었던 BigBear 태그 업데이트
커뮤니티에서 성공한 절차는 다음과 같습니다.
- ZimaOS 대시보드에서 Immich 앱의 점 3개 메뉴를 여세요.
- Settings를 선택하세요.
- immich-machine-learning 탭을 여세요.
- 이미지 Tag를 원하는 Immich 릴리스로 변경하세요.
- immich-server 탭을 여세요.
- 동일한 릴리스 태그를 설정하세요.
- 릴리스 노트에서 데이터베이스 또는 컨테이너 변경을 명시적으로 요구하지 않는 한, 데이터베이스 및 Redis 탭은 변경하지 않은 채로 두세요.
- 구성을 저장하고 ZimaOS가 영향을 받는 컨테이너를 다시 생성하고 가져오도록 하세요.
원래 답변 당시 예시 태그는 다음과 같았습니다.
v2.3.1해당 버전은 과거 버전입니다. 이후 다른 사용자가 다음 버전으로 업데이트했습니다 v2.4.1, 그리고 2026년 4월의 답변에서는 다음과 같이 언급했습니다 v2.7.4. 오늘은 이러한 이전 버전 번호를 그대로 복사하지 마세요. 현재 Immich 릴리스 노트와 업그레이드 경로를 확인한 후에만 대상 버전을 선택하세요.
원 게시자가 확인한 내용
BigBear 태그 지침을 받은 후 MikeFrizz는 그 팁이 매우 유용했으며 업데이트가 원활하게 완료되었다고 답했습니다. 이는 원문 스레드에서 확인된 가장 확실한 결과입니다.
이 확인 결과는 원 게시자가 사용한 패키지 및 버전 환경에서 해당 방법이 유효함을 뒷받침합니다. 그러나 두 태그를 수동으로 편집하는 것만으로 향후 모든 Immich 메이저 버전이나 모든 ZimaOS 패키지에서 충분하다는 의미는 아닙니다.
“latest” 태그가 문제를 해결할 것이라고 단정하지 마세요
한 사용자가 태그를 다음과 같이 변경했습니다. latest하지만 ZimaOS가 이전에 설치된 버전으로 반복해서 되돌아갔습니다. 이후 해당 스레드에는 다음과 같은 시도가 추측으로 제시됩니다. 릴리스하지만 이러한 일반적인 태그 이름을 바탕으로 소스에서 확인된 보편적인 해결 방법은 없습니다.
현재 Immich 문서에서는 명시적인 버전 변수를 사용하며, 자체 Docker Compose 워크플로에서 메이저 버전 메타태그를 지원합니다. 패키지형 ZimaOS 앱에서는 패키지 정의와 업스트림 이미지가 실제로 지원하는 태그 형식을 사용하세요. 이름이 그럴듯하다는 이유로 태그를 임의로 만들지 마세요.
버전을 변경하기 전에 Immich 백업하기
현재 Immich 문서에서는 마이그레이션이 포함될 수 있는 업그레이드 전에 데이터베이스를 백업할 것을 명시적으로 권장합니다. 사진과 동영상에도 별도의 백업 전략이 필요합니다. 데이터베이스 백업만으로는 미디어 라이브러리 자체를 대체할 수 없습니다.
수동으로 버전을 변경하기 전에 최신 Immich 백업 및 복원 가이드를 참조하세요.
최소한 다음 항목을 보존하세요.
- Immich 데이터베이스 백업
- 미디어 라이브러리/업로드 데이터
- 현재 ZimaOS 앱 구성 및 볼륨 매핑
- 현재 이미지 태그
- 및 모든 환경 변수나 사용자 지정 저장 위치
버전을 변경할 때마다 Immich 릴리스 노트 읽기
현재 Immich 업그레이드 문서에서는 관리자가 업데이트 전에 호환성이 깨지는 변경 사항이 있는지 릴리스 노트를 확인해야 한다고 안내합니다. 일반적인 업스트림 Docker Compose 절차는 다음과 같습니다.
docker compose pull && docker compose up -d단, Compose 정의와 버전 변수가 대상 릴리스에 맞는 경우에만 진행하세요.
현재 Immich 업그레이드 가이드를 참조하세요.
이는 패키지형 앱이 이미지 태그뿐 아니라 Compose에 상응하는 구성 정의에서도 뒤처질 수 있기 때문에 ZimaOS에서 중요합니다. 최신 immich-server 이미지에는 이전 패키지에 없는 데이터베이스, 환경 변수, 상태 확인 또는 볼륨 변경 사항이 필요할 수 있습니다.
Immich 서버와 머신 러닝 버전 호환성 유지
커뮤니티에서는 특히 두 항목의 태그를 변경했습니다 immich-server 및 immich-machine-learning현재 Immich 문서에서도 메인 서버와 머신 러닝 구성 요소 간의 버전이 일치하지 않으면 버그나 불안정성이 발생할 수 있다고 경고합니다.
사용 가능한 이미지가 먼저 표시되었다는 이유만으로 두 항목 중 하나만 업데이트하지 마세요. 현재 릴리스 문서에서 명시적으로 달리 안내하지 않는 한, 두 항목을 하나의 연동된 애플리케이션 버전으로 취급하세요.
데이터베이스 컨테이너 태그를 무작위로 변경하지 마세요.
데이터베이스 탭은 그대로 두라는 커뮤니티 조언은 해당 사례의 정확한 BigBear 마이너 업데이트에 대해서는 타당했습니다. Immich의 PostgreSQL 계층에는 자체 마이그레이션이 있으며, 시간이 지나면서 이전 벡터 확장에서 VectorChord로의 마이그레이션을 포함해 변경되어 왔습니다.
- 모든 태그의 숫자를 비슷하게 보이게 하려고 데이터베이스 이미지를 단순히 올리지 마세요.
- 현재 Immich 릴리스 노트에서 데이터베이스/Compose 마이그레이션이 필요하다고 안내하는 경우 데이터베이스 이미지는 절대 변경하면 안 된다고 단정하지 말고, 문서화된 마이그레이션을 따르세요.
기존 ZimaOS Immich 앱이 오래된 버전에 계속 머물러 있다면 어떻게 해야 하나요?
2026년 3월의 한 답변에서는 사용자가 BigBear App Store 버전을 실행하고 있지 않았으며, 머신 러닝 및 서버 이미지를 수동으로 업데이트하려고 시도한 후에도 Immich v2.1.0에 계속 머물러 있다고 했습니다. 해당 스레드에는 그 사용자의 원래 패키지 배포에 대한 확인된 해결 방법이 없습니다.
여기에는 중요한 기준이 있습니다. 이미지 태그를 수동으로 변경해도 앱이 업데이트되지 않는다면 같은 작업을 반복하지 말고 중단하세요. 패키지의 현재 컨테이너 정의를 Immich의 최신 Compose 요구 사항과 비교하고, 데이터를 백업하고 경로를 확인한 후에만 유지 관리되는 ZimaOS 패키지로의 마이그레이션을 고려하세요.
데이터베이스와 미디어 볼륨이 어디에 저장되어 있는지 알기 전에는 정상적으로 작동하는 Immich 패키지를 제거하지 마세요.
커뮤니티 사용자들이 BigBear Immich 패키지를 추천한 이유
첫 번째 답변에서는 BigBear Immich 앱이 일반적으로 업스트림 릴리스에 더 가깝게 유지되므로 이를 추천했습니다. 이후 성공한 태그 편집 지침도 BigBear에서 명시적으로 테스트되었습니다.
그렇다고 해서 기존 라이브러리에 대해 “BigBear 재설치”가 안전한 원클릭 마이그레이션 경로가 되는 것은 아닙니다. 새 패키지는 다른 볼륨 이름, 데이터 디렉터리, 데이터베이스 이미지 또는 환경 변수를 사용할 수 있습니다. 패키지 마이그레이션은 기존 스택 업그레이드와 별도의 작업으로 취급하세요.
자동 컨테이너 업데이트 프로그램 사용 시 주의
2026년 4월의 한 커뮤니티 답변에서는 컨테이너를 확인하고 자동으로 업데이트하는 더 쉬운 대안으로 Watchtower 대신 Tugtainer를 제안했습니다. 이 제안은 상태 비저장 서비스에는 편리할 수 있지만, Immich는 PostgreSQL 데이터베이스와 문서화된 호환성 변경 업그레이드 경로를 갖춘 상태 저장 멀티 컨테이너 애플리케이션입니다.
Immich의 경우 릴리스 노트를 확인하지 않고 이미지를 자동으로 교체하면 위험할 수 있습니다. 현재 Immich 문서에서는 업그레이드 전에 호환성을 깨뜨리는 변경 사항을 고려하라고 관리자에게 명확히 안내합니다. 자동 컨테이너 업데이트 프로그램을 사용하더라도 Immich는 새 태그가 나올 때마다 무작정 업데이트하기보다 알림 및 수동 승인을 사용하세요.
더 안전한 ZimaOS Immich 업데이트 워크플로
- 설치된 패키지가 BigBear인지, 아니면 다른 Immich 정의인지 기록하세요.
- 현재 서버, 머신 러닝, 데이터베이스 및 Redis 이미지/태그를 기록하세요.
- Immich 데이터베이스와 중요한 미디어를 백업하세요.
- 현재 버전과 대상 버전 사이에 호환성이 깨지는 변경 경계가 있다면 모두 업스트림 릴리스 노트를 읽으세요.
- 대상 버전에 Compose, 데이터베이스, 환경 변수 또는 스토리지 변경이 필요한지 확인하세요.
- 호환되는 BigBear 마이너 업데이트의 경우 커뮤니티에서 한 것처럼 서버와 머신러닝 태그를 함께 변경하세요.
- 문서화된 업그레이드 경로에서 변경을 명시적으로 요구하지 않는 한 데이터베이스/Redis 이미지는 변경하지 마세요.
- 앱 설정을 저장하고 새 이미지가 시작되는 동안 컨테이너 로그를 확인하세요.
- 이전 이미지를 삭제하기 전에 Immich 웹 UI 버전, 업로드, 썸네일, 머신러닝 및 기존 라이브러리를 확인하세요.
- 패키지가 즉시 롤백되거나 이전 버전으로 남아 있으면 태그를 반복해서 강제로 적용하기보다 패키지 정의를 확인하세요.
Immich 업데이트 후 확인할 사항
- 웹 UI가 로드되고 의도한 서버 버전을 표시합니다.
- 모바일 앱이 연결되고 서버의 메이저 버전과 호환됩니다.
- 기존 사진과 동영상이 정상적으로 열립니다.
- 새 업로드가 성공적으로 완료됩니다.
- 썸네일 생성 및 트랜스코딩 작업이 실행됩니다.
- 머신러닝 기능이 버전 불일치 오류 없이 시작됩니다.
- PostgreSQL 컨테이너는 정상 상태로 유지됩니다.
현재 Immich 문서에서는 다운그레이드를 지원되는 복구 전략으로 보지 않습니다. 데이터베이스 마이그레이션 후 태그만 간단히 되돌릴 수 있다고 가정하기보다 백업하는 편이 안전합니다.
ZimaOS Immich 업데이트 FAQ
ZimaOS 이미지 태그를 변경해서 Immich를 업데이트할 수 있나요?
일부 패키지/버전 조합에서는 가능합니다. 원 게시자와 다른 BigBear 사용자는 서버와 머신러닝 태그를 모두 변경하면 작동한다고 확인했습니다. 해당 스레드에는 이 방법으로 오래된 설치 문제가 해결되지 않은 BigBear 외부 사용자 사례도 있습니다.
어떤 Immich 태그를 변경해야 하나요?
확인된 BigBear 커뮤니티 방식에서는 다음이 적용됩니다. immich-server 및 immich-machine-learning 태그가 함께 변경되었습니다. 이전의 v2.3.1, v2.4.1 또는 v2.7.4 예시를 현재 대상 버전으로 그대로 사용하지 마세요.
latest를 사용해야 하나요?
보편적인 해결책은 아닙니다. 해당 스레드의 한 사용자는 다음과 같이 보고했습니다. latest 적용되지 않았습니다. 실제 패키지와 현재 Immich 지침에서 지원하는 버전 관리 체계를 사용하세요.
docker pull만 실행해도 되나요?
새 이미지만 가져온다고 해서 실행 중인 컨테이너가 다시 생성되거나 Compose 변경 사항이 적용되는 것은 아닙니다. 업스트림 Immich는 다음을 사용합니다. docker compose pull && docker compose up -d 대상 릴리스에 맞게 구성을 준비한 후입니다.
Tugtainer 또는 Watchtower가 Immich를 자동으로 업데이트해야 하나요?
자동 업데이트는 Immich에서 명시적으로 권장하는 릴리스 노트와 마이그레이션 검토를 건너뛸 수 있습니다. 데이터베이스가 있는 상태 저장 애플리케이션에서는 무작정 자동으로 교체하는 것보다 알림을 받고 통제된 수동 업그레이드를 진행하는 편이 더 안전합니다.
Immich를 업데이트하기 전에 백업이 필요한가요?
예. Immich의 현재 업그레이드 및 백업 문서에서는 업그레이드 전에 데이터베이스를 보호할 것을 권장하며, 대체할 수 없는 미디어도 별도로 보호해야 합니다.
