icloud_photos_downloader 安装与运行完全指南：Docker / PyPI / AUR / npm / 二进制五种方式详解

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官方提供三种运行途径：

1. 直接下载可执行文件：从 GitHub Releases 页下载对应平台的预编译二进制，直接运行；
2. 使用包管理器安装：通过 Docker、PyPI、AUR、npm 安装、升级，部分方式还可直接运行；
3. 从源码构建并运行。

典型的一次性/持续同步命令如下（以每小时为间隔持续监听 iCloud 变化）：

icloudpd --username your@email.address --directory photos --watch-with-interval 3600

三、直接下载可执行文件（推荐快速体验）

从 GitHub Release 页面 下载当前版本（本文档对应的发布版本为 v1.32.3）对应你平台的二进制文件，然后直接运行：

icloudpd --username your@email.address --directory photos --watch-with-interval 3600

该可执行文件由项目构建脚本产出，覆盖多平台架构。以 scripts/build_npm 中体现的发布矩阵为例，官方构建并分发以下平台组合：

macOS 二进制特例

icloudpd提供 Intel 64 位（amd64）macOS 二进制，同时也兼容 Apple Silicon（M1 / M2 / M3）芯片。首次运行需要按以下步骤放行系统安全校验：

1. 从 GitHub Releases 页面下载二进制到本地目标文件夹；
2. 添加可执行权限：chmod +x icloudpd-1.32.3-macos-amd64；
3. 在终端启动：icloudpd-1.32.3-macos-amd64；
4. 系统会提示“无法检查恶意软件”（cannot check for malicious software）并拒绝运行，点击“OK”；
5. 打开「系统设置 / 隐私与安全性」，在「安全性」中找到被拦截的icloudpd-1.32.3-macos-amd64，点击“允许”；
6. 再次从终端启动icloudpd-1.32.3-macos-amd64；
7. 系统会再次弹出警告，点击“打开”；
8. 之后即可正常运行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 TZ=America/Los_Angeles icloudpd/icloudpd:latest icloudpd --directory /data --username my@email.address --watch-with-interval 3600

参数含义说明：

• -v $(pwd)/Photos:/data：把宿主机当前目录下的Photos文件夹挂载为容器内的/data下载目录，照片将保存在宿主机上；
• -e TZ=America/Los_Angeles：指定时区。镜像中的资产日期会先转换到该时区，再用于创建下载子文件夹（受--folder-structure参数影响），因此建议把 TZ 设为你的本地时区；
• icloudpd --directory /data ...：镜像入口支持以icloudpd作为第一个参数来选择执行对应的二进制（详见仓库 Dockerfile 中的 entrypoint 脚本）。

同步逻辑可通过命令行参数调整，查看完整参数列表：

docker run -it --rm icloudpd/icloudpd:latest icloudpd --help

Windows 下的注意事项

• 用%cd%代替$(pwd)；
• 或直接使用完整路径，例如-v c:/photos/icloud:/data；
• 仅支持 Linux 容器（Windows 下需使用 WSL2 / Docker Desktop 的 Linux 容器模式）。

获取 Docker

• Windows 与 macOS：安装 Docker Desktop；
• Linux：使用发行版自带的包管理器安装 Docker 引擎与客户端（例如 Ubuntu 的apt install docker.io）；
• NAS 等设备：按照厂商说明安装 Docker 引擎并运行容器。

镜像结构佐证

仓库 Dockerfile 揭示了镜像的实现细节：镜像基于alpine:3.23，内置tzdata、musl-locales等时区与本地化组件，分别针对 amd64 / arm64 / arm32v7 三个目标架构拷贝静态二进制，并通过ENTRYPOINT ["/app/entrypoint.sh"]实现icloudpd/icloud两个命令的分发。这也解释了为什么容器启动时必须把icloudpd作为第一个参数。NAS 部署的具体案例可参考 docs/nas.md。

五、PyPI（pip）方式

Python 用户可以直接从 PyPI 安装：

pip install icloudpd

安装完成后运行：

icloudpd --directory /data --username my@email.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。确切路径同样会在安装结束时给出。

六、AUR（Arch Linux）方式

Arch Linux 用户可以通过 AUR 包安装（包名为icloudpd-bin），支持手动构建或使用 AUR 助手两种方式。

手动安装：

git clone https://aur.archlinux.org/icloudpd-bin.git cd icloudpd-bin makepkg -sirc

使用 AUR 助手（例如yay）：

yay -S icloudpd-bin

安装完成后直接运行icloudpd --help即可查看全部参数（参见 README_AUR.md）。

七、npm（Node.js）方式

无需手动安装二进制，借助 npm 生态可直接通过npx运行：

npx --yes icloudpd --directory /data --username my@email.address --watch-with-interval 3600

查看完整参数列表：

npx --yes icloudpd --help

npm 分发机制的实现原理

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/icloudpd（CLI 入口 src/icloudpd/cli.py、主流程 src/icloudpd/base.py）与 src/pyicloud_ipd（iCloud 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 my@email.address --directory photos --watch-with-interval 3600

运行测试（配置见 pyproject.toml 的[tool.pytest.ini_options]，测试用例位于 tests）：

pytest

说明：本文介绍从源码运行仅供查看与本地运行，仓库为只读性质，不涉及修改仓库内容。

九、首次运行报错排查：Bad Request (400)

第一次运行脚本时，可能会看到如下错误：

Bad Request (400)

原因：该错误通常是因为你的 Apple 账户此前从未使用过 iCloud 网页 API，Apple 服务器需要先为你的照片准备相关信息。这一过程大约需要5～10 分钟，请等待几分钟后重试。

如果 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）。以下是安装与初次运行时最常涉及的参数：

参数校验与互斥（源码佐证）

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/icloudpd（taglatest），容器参数逐项填入icloudpd -u your@email.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 选 Docker，Python 生态选 PyPI，Arch 用户选 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