由ReAI支持，挪威最自动化的会计系统。

将Google Photos图片批量转换为AVIF，并将视频优化为HEVC MP4，支持断点续传、相册迁移、拍摄日期校验、本地原始文件备份，以及经验证后从活跃图库中移除原始文件。

Python 3.15+，单一uv run入口，原生编码器，无需requirements.txt。Python依赖通过PEP 723在脚本中内联声明，由uv解析。你需要克隆仓库，因为入口点会导入其配套模块。

这是一个独立的实验性客户端，使用Google未公开的Web API。完整的真实图库迁移已通过一次全新的、完整分页的审计，包括修正后的Original质量视频上传。Google可能更改协议。请保留独立备份，并先尝试小批量。原始文件仅在验证通过后才会移入可恢复的Google Photos回收站；该工具从不清空回收站。Google自身的回收站保留规则仍然适用。

brew install uv libavif exiftool ffmpeg git clone https://github.com/gregjotau/google-photos-cli.git cd google-photos-cli uv run google-photos-cli.py doctor

如果尚未安装Google Chrome，请单独安装。FFmpeg必须包含libx265和AAC；libavif必须包含AOM编码器。doctor会检查已安装工具的版本。在Linux上，请安装对应的原生包和Chrome；Linux支持尚未经过端到端验证。Windows目前不受支持，因为进程锁使用了fcntl。

uv会自动选择Python 3.15或更高版本，并创建缓存的依赖环境。无需手动配置virtualenv或pip。脚本附带锁文件；使用uv run --locked google-photos-cli.py …可获得锁定依赖解析。

uv run google-photos-cli.py connect

在打开的Chrome窗口中登录目标Google账户。如果Chrome询问是否允许连接本地设备，请允许。保持该终端和标签页打开。此操作使用独立的持久化Chrome配置文件；它不会读取你正常的Chrome配置文件，也不会将Google cookie导出给Python。

在优化视频之前，请将Google Photos → 设置 → 备份质量设为Original质量。这样可以保留此工具已压缩的小文件。即使初次字节级验证通过，Storage saver也可能异步将上传的HEVC文件重写为更大、不同的文件。除非Google报告其替换文件为Original质量，否则客户端拒绝将视频源移入回收站。更改该设置会影响你的网页上传偏好；CLI不会自动更改它。

参见已测量的Storage saver问题及恢复流程：一次HEVC上传从3.77 MB增长为10.43 MB的VP9原始导出。这是对此优化器输出使用Original质量的理由，而非一概反对其他媒体使用Storage saver。下载文件大小和计费存储配额是两项独立的度量。

只读：对图库进行快照并预览少量选择。

uv run google-photos-cli.py plan --year current --limit 5

处理同样的五个匹配资产。

uv run google-photos-cli.py run --year current --limit 5 --apply

处理当前年份，恢复之前的工作。

uv run google-photos-cli.py run --year current --apply

或处理整个已保存的图库和归档。

uv run google-photos-cli.py run --apply

run、migrate和videos默认仅预览。云端上传和将原始文件移入回收站需要--apply。--dry-run始终覆盖--apply。首次预览可以获取清单和元数据，但绝不会上传或将媒体移入回收站。在有完整缓存快照的情况下，预览可离线工作。

已有的AVIF图片会被保留。合并的Live/Motion Photos会完整保留，不会拆分为独立的静态图片和视频项。Locked Folder、未保存的共享项以及已在回收站中的项不在迁移范围内。

筛选器可用于plan、run、migrate、videos和audit。不同类型的筛选器以AND组合。重复的年份或相册ID匹配所提供值中的任意一个。

日期使用拍摄时间戳及其记录的UTC偏移，而非上传日期或你当前的时区。缺失偏移视为UTC。请为文件名glob加引号，以防止shell展开它们。相册ID是Google Photos相册URL中的标识符，例如/album/之后的部分。

两年的图片，排除收藏。

uv run google-photos-cli.py run --media images --year 2024 --year 2025 --exclude-favorites --apply

日期范围内拍摄的大视频。

uv run google-photos-cli.py run --media videos --from-date 2024-01-01 --to-date 2025-12-31 --min-size-mb 10 --apply

仅预览某个相册中的JPEG。

uv run google-photos-cli.py plan --album ALBUM_ID --filename '*.jpg'

显式试运行，即使同时提供了--apply。

uv run google-photos-cli.py run --year current --apply --dry-run

limit在恢复过程中保持稳定，并包含已处理或保持不变的匹配资产。重复--limit 5会处理同样的前五个，而不会推进到另外五个。移除或增大该值以扩大选择范围。对于跨新年的长期任务，请复用相同的数字年份；current在每次调用时重新解析。

媒体 默认值 图片 libavif/libaom AVIF；质量45，速度6，10位YUV420；方向归一化到像素中 视频 HEVC Main10 MP4，hvc1；x265 medium，CRF 30；横屏或竖屏最高1080p，最高30 fps；AAC 96 kbps立体声；fast-start 并发 四个图片工作线程，每张图片三个AOM线程，一个视频编码器使用四个x265池线程

（原文较长，此处译出前 6000 字，完整内容请点「打开原文」。）