iCloud Photos Downloader

 (github.com/icloud-photos-downloader)
3P by GN⁺ | ★ favorite | 댓글 1개
  • iCloud 계정의 사진을 명령줄에서 직접 다운로드할 수 있게 하는 오픈소스 도구
  • Linux, Windows, macOS 등 주요 운영체제에서 실행 가능하며, Docker·PyPI·AUR·npm을 통한 설치 지원
  • Copy·Sync·Move 세 가지 모드로 작동하며, Live Photos·RAW 이미지·EXIF 메타데이터 처리 기능 포함
  • 자동 중복 제거, 지속적 변경 감시, 증분 실행 최적화 등 다양한 옵션 제공
  • MIT 라이선스로 공개되어 있으며, 현재 유지보수 담당자(maintainer) 를 찾고 있음

프로젝트 개요

  • iCloud Photos Downloader는 iCloud에 저장된 사진을 로컬 시스템으로 내려받는 명령줄 기반 도구
    • iCloud 사진 전체를 다운로드하거나, 변경 사항만 동기화 가능
    • 자원봉사자 커뮤니티가 개발 및 유지 중이며, 신규 기여자를 모집 중
  • MIT 라이선스로 배포되어 자유로운 사용과 수정 가능
  • GitHub에서 10k개 이상의 별(star) 과 705개의 포크(fork) 를 보유

지원 플랫폼 및 배포 방식

  • 운영체제 호환성: Linux, Windows, macOS, NAS 환경 지원
  • 배포 채널:
    • Docker 이미지
    • PyPI 패키지
    • Arch Linux AUR
    • npm 패키지
  • 실행 파일을 직접 다운로드하거나, 소스 코드에서 빌드 가능

주요 기능

  • 세 가지 작동 모드
    • Copy: 새 사진만 다운로드 (기본 모드)
    • Sync: iCloud에서 삭제된 사진을 로컬에서도 삭제 (--auto-delete)
    • Move: 다운로드 후 iCloud에서 사진 삭제 (--keep-icloud-recent-days)
  • 지원 포맷: Live Photos(이미지·비디오 분리 저장), RAW 및 RAW+JPEG
  • 기능 옵션
    • 동일 이름 사진의 자동 중복 제거
    • 지속 감시 모드 (--watch-with-interval)
    • 증분 실행 최적화 (--until-found, --recent)
    • EXIF 메타데이터 수정 (--set-exif-datetime)
  • --help 명령으로 전체 옵션 확인 가능

설치 및 실행

  • 설치 방법
    1. GitHub 릴리스 페이지에서 실행 파일 다운로드
    2. 패키지 매니저(Docker, PyPI, AUR, npm)로 설치
    3. 소스 코드 직접 빌드
  • iCloud 설정 요구사항
    • iPhone/iPad에서 Access iCloud Data on the Web 활성화
    • Advanced Data Protection 비활성화 필요
  • 사용 예시
    • 동기화 실행: 
      icloudpd --directory /data --username my@email.address --watch-with-interval 3600
    • 인증 세션 생성: 
      icloudpd --username my@email.address --password my_password --auth-only

실험적 기능 및 개발 현황

  • 일부 기능은 Experimental Mode로 먼저 추가되어 검증 후 정식 반영
  • 최신 릴리스는 v1.32.2 (2025년 9월 2일)
  • 주 1회(금요일) 를 목표로 새로운 버전 배포
  • 최근 커밋에서는 다중 사용자 설정 지원, 비리눅스 빌드 수정, 테스트 환경 개선 등이 포함됨

기여 및 커뮤니티

  • 기여 가이드라인(CONTRIBUTING.md) 를 통해 외부 개발자 참여 가능
  • 42명의 기여자가 코드에 참여했으며, Dependabot 등 자동화 도구도 사용
  • 현재 프로젝트 유지보수자를 공개 모집 중
  • 공식 문서와 토론은 GitHub Discussions에서 진행

함께 보면 좋은 글 β

GN⁺   [-]
Hacker News 의견들

  • 나는 Photos Backup Anywhere의 제작자임. Apple Photos를 분석하면서 놀랐던 점은 단순히 디스크의 파일만으로는 전체 상태를 표현할 수 없다는 것임
    앨범, Live Photos, 연속 촬영, 슬로모션, 편집 내역, 촬영일 수정 등은 별도로 관리되며, 대부분의 백업 도구는 이를 복원 시 제대로 재구성하지 못함
    그래서 나는 Photos 자체를 진실의 원본(source of truth) 으로 보고, 복원 시 이를 기준으로 검증하는 방식을 택했음
    이 도구는 앨범과 모든 사진 유형을 완전하게 복원하면서 위치, 생성일, 수정일을 유지함
    프로젝트 페이지는 photosbackup.app 에 있음

    • 나는 iPhone에서 사진을 옮길 때 ‘Image Capture’ 앱으로 0~9999 단위로 복사함. 1만 장이 넘으면 파일명이 다시 00001(1)로 바뀌어버려서 불편함
      MacBook SSD 용량이 작고 iCloud를 거치고 싶지 않은데, 원본 RAW/JPEG/Live/Video를 외장 드라이브로 직접 내보낼 방법이 있는지 궁금함
    • 오래된 Android 폰에서 사진을 추출하는 데 정말 악몽 같은 경험을 했음. 인터페이스가 제대로 안 뜨면 드라이브 전체를 긁어모으는 도구에 의존해야 함
    • 혹시 S3 호환 스토리지(예: Backblaze B2)로 백업을 지원하는지 궁금함
    • 혹시 Parachute Backup을 살펴본 적 있는지? 그쪽도 iPhotos의 복잡한 데이터까지 백업 가능하다고 주장함

  • 이 프로젝트 정말 멋짐. Windows용 iCloud 앱을 대신할 수 있을지도 모르겠음
    나도 약 2TB의 iCloud 데이터를 가지고 있는데, MacBook은 용량이 부족하고 외장 드라이브에 별도의 Photo Library를 두고 있음
    Windows용 iCloud 앱은 항상 50MB/s로 다운로드 중이지만, 폴더를 열면 대부분 ‘온라인에서만 사용 가능’ 상태임
    현재 944GB 정도 내려받았는데, 완전히 끝나려면 시간이 걸릴 듯함
    Windows에서 HEIC와 Live Photo를 제대로 보여주는 대체 사진 뷰어가 있는지 궁금함

  • macOS 전용이지만 유료 프로그램 Parachute가 있음. iCloud 라이브러리의 사진과 파일을 모두 다운로드할 수 있음
    App Store 링크

    • iOS에서는 PhotoSync도 괜찮음. 사진을 NAS나 B2 같은 원격 서비스로 전송 가능함
    • Parachute는 데스크톱 버전은 안정적이지만, iOS 버전은 1TB 라이브러리의 증분 백업을 밤새 완료하지 못함
      원본은 내보내지만 AAE 파일은 포함하지 않음. 반면 PhotoSync는 복원 기능이 없다는 점이 아쉬움
    • ADP 계정과 호환되는지 문의했지만 답변을 못 받았음. ADP 계정용으로 쓸만한 다운로드 솔루션이 있는지도 궁금함
    • 개인정보 측면에서 안전성 검증이 가능한지, Windows용 대안이 있는지도 알고 싶음

  • 놀랍게도 iCloud에서 모든 사진(약 400GB)을 한 번에 다운로드하는 공식 방법이 없음
    대신 오픈소스 명령줄 도구로 전체 iCloud 사진을 받을 수 있음

    • 사실 Mac이나 iPhone에서는 iCloud Photo Library 설정에서 ‘원본 다운로드’를 선택하면 전체 다운로드 가능함
    • EU 사용자라면 privacy.apple.com 에서 Apple이 보유한 모든 데이터를 요청할 수 있음
    • Mac의 Photos 앱에서는 Cmd+A > File > Export Unmodified Originals 로 원본을 내보낼 수 있음
    • Apple이 사용자가 떠나지 않게 하려는 의도일 수도 있음. 사진 이동을 어렵게 만드는 건 락인 전략처럼 보임

  • 며칠 전 공유 라이브러리를 백업했는데, 약 10K개의 사진·영상(300GB)을 다루었음
    iPhoto 라이브러리 복구 → 연도별로 나눠 내보내기 → 외장 HDD로 이동 → 외장 HDD 라이브러리를 기본으로 지정 후 iCloud 재동기화
    유선 이더넷 연결과 Repair 기능이 큰 도움이 되었음

    • Photos Library 파일을 외장 HDD로 옮기고 Photos.app에서 그 경로를 지정하는 것과 차이가 있는지 궁금함

  • 나는 usbmuxd + ifuse 조합으로 iPhone에서 직접 사진 파일을 복사함
    업로드나 다운로드 대기 없이 케이블로 바로 연결해 원본을 가져오고, 심지어 이동시켜 공간 확보도 가능함

    • 이 방식이 모든 iPhone에서 가능한지 궁금함. USB로 DCIM 폴더를 마운트해서 쓰기 권한까지 얻을 수 있는지 알고 싶음

  • 나는 작은 쉘 스크립트로 주기적으로 iCloud 사진을 내려받음
    icloudpd/icloudpd:latest 컨테이너를 사용해 폴더 구조별로 원본을 저장함

    • 하지만 최신 태그(latest) 를 그대로 쓰는 건 위험함. 검증되지 않은 이미지에 iCloud 자격 증명을 넘기는 건 좋지 않음. 특정 버전이나 해시로 고정하는 게 안전함

  • 우리 가족은 매년 약 2TB의 미디어를 생성함. 총 12TB 정도 됨
    iCloud의 추억 기능은 좋지만 월 60달러는 부담스러워서 다음과 같이 함

    • docker-icloudpd로 여러 계정의 사진을 로컬 스토리지에 백업
    • 최근 2년치만 iCloud에 남기고, 이전 것은 로컬에 보관
    • 오래된 사진은 Immich로 탐색·검색함. 자체 호스팅이지만 앱 경험이 훌륭함
      빠른 로컬 디스크(예: OWC 4M2 + M.2 SSD)가 중요함. HDD 기반 NAS는 느림
      docker-icloudpd GitHub 링크
    • Photos에서 사용하는 기능 중 Immich에 없는 게 있는지 궁금함. 나는 Android라 Immich만으로 충분히 만족 중임

  • iCloud Photos.app에서는 일부 사진이 안 보이는데, Photometor.app(Apple 소유)에서는 보임
    Photos.app에서 안 보이는 이유를 알 수 없어서 답답함

  • Apple이 서드파티 통합을 거의 허용하지 않는 게 아쉬움
    특정 앨범의 사진을 부모님 액자나 Samsung Frame TV로 자동 동기화하고 싶은데, 이런 기능이 막혀 있음
    약간만 개방해도 혁신적인 활용이 가능할 것 같음

    • 나는 PhotoSync로 이 문제를 해결함. 앨범별로 동기화 규칙을 정해 자동 전송함
답변달기