icloudpd 完整安装教程：5 种方式快速备份 iCloud 照片和视频
【免费下载链接】icloud_photos_downloaderA command-line tool to download photos from iCloud项目地址: https://gitcode.com/GitHub_Trending/ic/icloud_photos_downloader
icloudpd 是一个开源的命令行工具，专门用来批量下载、备份 iCloud 里的照片和视频，还能按拍摄时间自动建文件夹、支持定时增量同步，让你只拉取新照片。全文只给你"能直接跑起来"的最短命令，不用写代码，照着敲即可，Windows、macOS、Linux 都适用。
你该选哪种安装方式
先花 10 秒判断自己属于哪一类，能少走弯路：
- 想长期定时同步、或跑在 NAS 上→ 用 Docker，环境完全隔离，升级最省心。
- 机器上已经装了 Python→ 直接
pip装，最快。 - 只是临时拉一次照片→ 用
npx，装完即走，不留残留。 - 只装了 Arch Linux→ 走 AUR，一条命令搞定。
- macOS 上不想折腾依赖→ 下原生二进制，加个执行权限就能跑。
对照表如下，按你的环境对号入座：
| 安装方式 | 适合人群 | 覆盖平台 |
|---|---|---|
| Docker | 长期定时同步、跑在 NAS 上 | Windows / macOS / Linux |
| PyPI（pip） | 已有 Python 环境 | 全平台 |
| npm（npx） | 临时用一次 | 全平台 |
| AUR | Arch Linux 用户 | Arch / Manjaro |
| 原生二进制 | macOS 不想装依赖 | macOS（含 Intel / Apple 芯片） |
主推路径：Docker 一行命令持续同步
Docker 方式把工具、依赖、运行环境全打包进一个容器，你本机装不装 Python 都无所谓，也是 NAS 用户的首选。下面按"装 → 配参数 → 跑起来 → 验证"四步走。
第 1 步，准备容器运行时。Windows 和 macOS 直接装 Docker Desktop 即可；Linux 用系统自带包管理器装 docker 引擎和客户端；NAS 则按厂商文档装 Docker 并起容器。
第 2 步，理解这条命令里每个参数在干什么。下面这条命令做三件事：把你本机的Photos文件夹映射进容器、把照片按东八区时区归类、每小时自动检查一次新增照片。
docker run -it --rm --name icloudpd \ -v $(pwd)/Photos:/data \ -e TZ=Asia/Shanghai \ icloudpd/icloudpd:latest \ icloudpd --directory /data --username 你的邮箱 --watch-with-interval 3600逐个参数说明：
-v $(pwd)/Photos:/data：把当前目录下的Photos文件夹挂进容器的/data，下载结果就落在这里。-e TZ=Asia/Shanghai：指定时区，决定照片按哪个时区建"年/月"文件夹，跨时区归档很重要。--directory /data：告诉工具在容器内往哪个目录存。--username 你的邮箱：换成你的 Apple ID 邮箱。--watch-with-interval 3600：保持进程常驻，每 3600 秒（1 小时）检查一次新照片，只拉增量，避免高频请求。
第 3 步，跑起来。回车后会进入交互流程，按提示输入 Apple ID、密码，必要时完成双重验证。看到日志里开始列出并下载照片，就说明连上了。
第 4 步，验证结果。回到本机Photos文件夹，确认出现了按日期命名的子目录和图片文件；再执行下面这条，能打印出完整参数列表即代表安装无误：
docker run -it --rm icloudpd/icloudpd:latest icloudpd --help其他平台最快上手
不想用容器？下面各给一条最短可用命令，挑你的平台照抄即可。
macOS：pip 或原生二进制
有 Python 的话，一条命令装完直接跑：
pip install icloudpd icloudpd --directory ~/icloud-photos --username 你的邮箱 --watch-with-interval 3600装完若提示command not found，把安装输出里给出的那个bin路径加进 PATH 即可。
更"零依赖"的做法是下原生二进制（Intel 版，Apple 芯片也能跑）：从 Release 页面下载后，给它执行权限，再运行。
chmod +x icloudpd-版本号-macos-amd64 ./icloudpd-版本号-macos-amd64 --helpmacOS 第一次运行会拦你，去"系统设置 → 隐私与安全性"里点"仍要允许"，再跑一次点"打开"，之后就能正常用了。
Windows：pip --user 装一次
在cmd或 PowerShell 里执行，--user表示装到当前用户目录、不污染系统：
pip install icloudpd --user icloudpd --directory C:\Photos\iCloud --username 你的邮箱 --watch-with-interval 3600若提示找不到命令，把安装结束时打印的...\Scripts目录加进系统 PATH，再新开一个终端窗口即可。
提示：执行入口是
icloudpd，不是icloud，敲错会报"不是内部或外部命令"。
Arch Linux：AUR 一条命令
用 AUR 助手（如 yay）一行装好预编译包：
yay -S icloudpd-bin icloudpd --directory ~/icloud-photos --username 你的邮箱 --watch-with-interval 3600不装助手的话，手动构建的最后一步是makepkg -sirc（先拿到对应的 AUR 源码包再执行）。
装完不会用？3 类常见报错与处理
报错不可怕，把症状对到原因，基本一步就能解决。
① 首次运行报Bad Request (400)
- 意味着什么：你的账户是头一次通过 API 访问，Apple 服务器还没把照片清单准备好。
- 怎么办：等 5–10 分钟后重跑；超过 30 分钟仍报错，再带上完整日志去提 issue。
②icloudpd找不到命令 / 不是内部或外部命令
- 意味着什么：命令目录不在 PATH，或你敲成了
icloud。 - 怎么办：确认二进制名叫
icloudpd，并把 pip 输出里给的Scripts（Windows）或Library/Python/.../bin（macOS）目录加进 PATH 后新开终端。
③ACCESS_DENIED拒绝访问
- 意味着什么：iCloud 侧的权限开关没打开，Apple 直接拒了连接。
- 怎么办：在 iPhone/iPad 上打开"设置 → Apple ID → iCloud"，开启"在网页上访问 iCloud 数据"，并关闭"高级数据保护"，然后重试。
让照片持续留在本地
装好之后，--watch-with-interval会让它常驻并只拉新增，配合定时任务就是你自己的"照片自动备份机"。想改同步行为、目录结构或认证方式，直接看对应模块：核心下载逻辑在 src/icloudpd/download.py，命令行入口在 src/icloudpd/cli.py，配置管理在 src/icloudpd/config.py，认证流程在 src/icloudpd/authentication.py。更多参数跑icloudpd --help就能查到。
【免费下载链接】icloud_photos_downloaderA command-line tool to download photos from iCloud项目地址: https://gitcode.com/GitHub_Trending/ic/icloud_photos_downloader
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
