
icloud_photos_downloader 安装与运行完全指南Docker / PyPI / AUR / npm / 二进制五种方式详解【免费下载链接】icloud_photos_downloaderA command-line tool to download photos from iCloud项目地址: https://gitcode.com/GitHub_Trending/ic/icloud_photos_downloader导读icloud_photos_downloader 是一个命令行工具用于把 iCloud 照片与视频批量下载到本地存储支持 Linux、Windows、macOS 以及各类 NAS 设备。本文以官方文档 docs/install.md 为主线系统梳理 icloudpd 的全部安装与运行途径——从直接下载平台二进制文件到 Docker、PyPI、AUR、npm 等包管理器方案再到从源码构建运行——并补充首次运行时常见错误的排查方法。读完本文你将能根据自己的操作系统与使用场景选择最合适的安装方式并正确启动持续同步任务。提醒实际可执行命令是icloudpd不是icloud运行前请确保 iCloud 账户已满足前置条件否则 Apple 服务器会返回ACCESS_DENIED。一、安装前的 iCloud 账户前置条件在安装之前需要先确认 iCloud 账户已开启以下两项设置详见 README.md 的 iCloud Prerequisites 一节否则 Apple 服务器将返回ACCESS_DENIED错误开启「网页访问 iCloud 数据」在 iPhone / iPad 上进入设置 Apple ID iCloud 通过网页访问 iCloud 数据Access iCloud Data on the Web并启用关闭「高级数据保护」在 iPhone / iPad 上进入设置 Apple ID iCloud 高级数据保护Advanced Data Protection并关闭。二、三种运行方式总览icloudpd官方提供三种运行途径直接下载可执行文件从 GitHub Releases 页下载对应平台的预编译二进制直接运行使用包管理器安装通过 Docker、PyPI、AUR、npm 安装、升级部分方式还可直接运行从源码构建并运行。典型的一次性/持续同步命令如下以每小时为间隔持续监听 iCloud 变化icloudpd --username youremail.address --directory photos --watch-with-interval 3600三、直接下载可执行文件推荐快速体验从 GitHub Release 页面 下载当前版本本文档对应的发布版本为 v1.32.3对应你平台的二进制文件然后直接运行icloudpd --username youremail.address --directory photos --watch-with-interval 3600该可执行文件由项目构建脚本产出覆盖多平台架构。以 scripts/build_npm 中体现的发布矩阵为例官方构建并分发以下平台组合平台架构产物命名示意Linuxx64 (amd64)icloudpd-version-linux-amd64Linuxarm64icloudpd-version-linux-arm64Linuxarm (arm32v7)icloudpd-version-linux-arm32v7Windowsx64icloudpd-version-windows-amd64.exemacOSx64 (amd64)icloudpd-version-macos-amd64macOS 二进制特例icloudpd提供 Intel 64 位amd64macOS 二进制同时也兼容 Apple SiliconM1 / M2 / M3芯片。首次运行需要按以下步骤放行系统安全校验从 GitHub Releases 页面下载二进制到本地目标文件夹添加可执行权限chmod x icloudpd-1.32.3-macos-amd64在终端启动icloudpd-1.32.3-macos-amd64系统会提示“无法检查恶意软件”cannot check for malicious software并拒绝运行点击“OK”打开「系统设置 / 隐私与安全性」在「安全性」中找到被拦截的icloudpd-1.32.3-macos-amd64点击“允许”再次从终端启动icloudpd-1.32.3-macos-amd64系统会再次弹出警告点击“打开”之后即可正常运行icloudpd-1.32.3-macos-amd64 --help或执行任意受支持的命令/参数。在 macOS 上使用 npm 包补充如果你通过 npm 方式在 macOS 上使用 icloudpd构建脚本 scripts/build_npm 目前为 darwin-arm64 打包的同样是 Intel 二进制注释 using Intel binary for now因此两种架构在 macOS 上实际执行的是同一份 x64 可执行文件同样可以通过 Rosetta 运行。四、Docker 容器方式Docker 是 NAS、服务器以及追求“免装环境”场景下最常用的方式一条命令即可完成拉取镜像并运行docker run -it --rm --name icloudpd -v $(pwd)/Photos:/data -e TZAmerica/Los_Angeles icloudpd/icloudpd:latest icloudpd --directory /data --username myemail.address --watch-with-interval 3600参数含义说明-v $(pwd)/Photos:/data把宿主机当前目录下的Photos文件夹挂载为容器内的/data下载目录照片将保存在宿主机上-e TZAmerica/Los_Angeles指定时区。镜像中的资产日期会先转换到该时区再用于创建下载子文件夹受--folder-structure参数影响因此建议把 TZ 设为你的本地时区icloudpd --directory /data ...镜像入口支持以icloudpd作为第一个参数来选择执行对应的二进制详见仓库 Dockerfile 中的 entrypoint 脚本。同步逻辑可通过命令行参数调整查看完整参数列表docker run -it --rm icloudpd/icloudpd:latest icloudpd --helpWindows 下的注意事项用%cd%代替$(pwd)或直接使用完整路径例如-v c:/photos/icloud:/data仅支持 Linux 容器Windows 下需使用 WSL2 / Docker Desktop 的 Linux 容器模式。获取 DockerWindows 与 macOS安装 Docker DesktopLinux使用发行版自带的包管理器安装 Docker 引擎与客户端例如 Ubuntu 的apt install docker.ioNAS 等设备按照厂商说明安装 Docker 引擎并运行容器。镜像结构佐证仓库 Dockerfile 揭示了镜像的实现细节镜像基于alpine:3.23内置tzdata、musl-locales等时区与本地化组件分别针对 amd64 / arm64 / arm32v7 三个目标架构拷贝静态二进制并通过ENTRYPOINT [/app/entrypoint.sh]实现icloudpd/icloud两个命令的分发。这也解释了为什么容器启动时必须把icloudpd作为第一个参数。NAS 部署的具体案例可参考 docs/nas.md。五、PyPIpip方式Python 用户可以直接从 PyPI 安装pip install icloudpd安装完成后运行icloudpd --directory /data --username myemail.address --watch-with-interval 3600安装包定义的版本与入口可在 pyproject.toml 中确认项目版本为 1.32.3要求 Python 版本3.10,3.14并注册了两个控制台命令入口icloudpd icloudpd.cli:cli主下载工具icloud pyicloud_ipd.cmdline:main配套会话/认证工具。因此pip install icloudpd之后icloudpd与icloud两个命令都会出现在你的 PATH 中。依赖方面项目将requests、schema、tqdm、piexif、Flask、waitress、keyring、srp等库锁定为精确版本以保证可复现性。Windows 上的安装提示pip install icloudpd --user同时需要把C:\Users\你的用户名\AppData\Roaming\Python\Python你的Python版本\Scripts添加到 PATH。安装结束时终端给出的确切路径即为该目录。macOS 上的安装提示把/Users/你的用户名/Library/Python/你的Python版本/bin添加到 PATH。确切路径同样会在安装结束时给出。六、AURArch Linux方式Arch Linux 用户可以通过 AUR 包安装包名为icloudpd-bin支持手动构建或使用 AUR 助手两种方式。手动安装git clone https://aur.archlinux.org/icloudpd-bin.git cd icloudpd-bin makepkg -sirc使用 AUR 助手例如yayyay -S icloudpd-bin安装完成后直接运行icloudpd --help即可查看全部参数参见 README_AUR.md。七、npmNode.js方式无需手动安装二进制借助 npm 生态可直接通过npx运行npx --yes icloudpd --directory /data --username myemail.address --watch-with-interval 3600查看完整参数列表npx --yes icloudpd --helpnpm 分发机制的实现原理npm 包本质上是“平台二进制分发器”主包 npm/icloudpd/package.json 通过optionalDependencies声明了六个平台子包icloudpd/linux-arm、linux-arm64、linux-x64、win32-x64、darwin-x64、darwin-arm64每个子包内含对应平台的二进制文件安装时执行 npm/icloudpd/preinstall.js该脚本根据process.platform os.arch os.endianness组合如linux x64 LE校验当前平台是否受支持不受支持则直接抛错退出。这也是npx --yes icloudpd能够在各平台“零配置”拉起正确二进制的底层原因。八、从源码构建与运行开发者方式对于希望参与开发、调试或研究实现细节的用户可以从源码直接运行。仓库采用src/布局的 Python 包结构核心代码位于 src/icloudpdCLI 入口 src/icloudpd/cli.py、主流程 src/icloudpd/base.py与 src/pyicloud_ipdiCloud API 客户端。安装开发依赖可参考 scripts/install_deps它会安装requirements-pip.txt并以可编辑模式安装当前包及test、dev、doc分组依赖python3 -m pip install --disable-pip-version-check -r requirements-pip.txt pip3 install --disable-pip-version-check -e . --group test --group dev --group doc之后即可直接运行icloudpd --username myemail.address --directory photos --watch-with-interval 3600运行测试配置见 pyproject.toml 的[tool.pytest.ini_options]测试用例位于 testspytest说明本文介绍从源码运行仅供查看与本地运行仓库为只读性质不涉及修改仓库内容。九、首次运行报错排查Bad Request (400)第一次运行脚本时可能会看到如下错误Bad Request (400)原因该错误通常是因为你的 Apple 账户此前从未使用过 iCloud 网页 APIApple 服务器需要先为你的照片准备相关信息。这一过程大约需要510 分钟请等待几分钟后重试。如果 30 分钟后仍然报错请前往项目 GitHub Issues 页面新建 issue并附上脚本的完整输出便于维护者定位问题。从源码结构看认证与 API 交互集中在 src/pyicloud_ipd/session.py 与 src/icloudpd/authentication.py遇到Bad Request类错误时--log-level debug默认即 debug输出会包含更多可诊断信息。十、运行参数速览--help与常用参数无论采用哪种安装方式同步行为都由命令行参数控制完整参数说明见 docs/reference.md参数解析实现见 src/icloudpd/cli.py。以下是安装与初次运行时最常涉及的参数参数作用默认值-d, --directory DIR本地下载根目录必填除非使用--auth-only等无-u, --username EMAILApple ID 邮箱可多次指定以配置多个账户无--watch-with-interval SEC以指定秒数为周期无限循环监听 iCloud 变化如 3600 每小时不启用--auth-only仅创建/更新 cookie 与会话令牌后退出用于预认证不启用--cookie-directory DIR存放认证 cookie 的目录~/.pyicloud--domain com\|cn指定 iCloud 根域名大陆地区使用cncom--folder-structure FMT下载子文件夹命名格式如{:%Y/%m/%d}none表示平铺{:%Y/%m/%d}--log-level debug\|info\|error日志级别debug--no-progress-bar关闭单行进度条重定向输出到文件时推荐不启用参数校验与互斥源码佐证src/icloudpd/cli.py 的cli()函数在真正执行前会做若干校验安装后运行命令时如违反这些规则程序会以退出码 2 报错并给出提示--skip-videos与--skip-photos在同一配置中互斥每个配置必须提供--auth-only、--directory、--list-libraries或--list-albums之一--auto-delete与--delete-after-download互斥--keep-icloud-recent-days不应与--delete-after-download同用--watch-with-interval与--list-albums、--list-libraries、--only-print-filenames、--auth-only不兼容。另外--folder-structure的取值会被validate_folder_structure()用datetime格式化验证非法格式会直接报Format ... specified in --folder-structure is incorrect。--watch-with-interval的主循环实现在 src/icloudpd/base.py 的run_with_configs()中每次循环会重新执行一次完整同步并在等待期间显示Waiting for interval sec...进度。十一、进阶参考在 NAS 上部署若需在 NAS如 TrueNAS / Synology上长期运行官方文档 docs/nas.md 提供了完整案例。以 TrueNAS 的「Install Custom App」为例核心配置为镜像仓库填icloudpd/icloudpdtaglatest容器参数逐项填入icloudpd -u youremail.address -d /data --password-provider webui --mfa-provider webui --watch-with-interval 3600每个参数名与参数值各作为一个独立 arg并开放容器端口8080映射到宿主机端口如9090之后通过浏览器访问 WebUI 完成密码与 MFA 输入。关于 WebUI 认证的细节见 docs/webui.md。结语icloudpd的安装方式覆盖了从“开箱即用”到“深度定制”的全部需求临时体验选二进制或npx服务器与 NAS 选 DockerPython 生态选 PyPIArch 用户选 AUR二次开发则从源码运行。配合--watch-with-interval持续同步参数与--auth-only预认证机制即可把 iCloud 照片库稳定、增量地备份到本地。【免费下载链接】icloud_photos_downloaderA command-line tool to download photos from iCloud项目地址: https://gitcode.com/GitHub_Trending/ic/icloud_photos_downloader创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考