DateFrame organizes photo and video libraries around their capture date. It can rename media, repair date metadata, import from iCloud Photos on Windows, keep supported sidecars and Apple Live Photo pairs together, and resume long operations from detailed logs.
Install the published package with Python 3.10 or newer:
pip install dateframeThis installs a single command:
dateframe --helpYou do not need to clone this repository to use DateFrame. Cloning is only needed for development or contributing.
Import files directly from iCloud Photos on Windows:
dateframe import-icloud "C:\Users\You\Pictures\iCloud Photos\Photos" "C:\Users\You\Pictures\iCloud-Renamed"Copy and rename media from a camera folder or export:
dateframe rename --copy "/path/to/originals" "/path/to/renamed"Write filename dates back into media metadata:
dateframe write-dates "/path/to/renamed"| Command | Purpose |
|---|---|
dateframe import-icloud |
Import and rename media from iCloud Photos for Windows using available iCloud/Windows date metadata. |
dateframe rename |
Copy or move media into timestamp-based filenames using embedded metadata and associated sidecars. |
dateframe write-dates |
Write capture dates from timestamped filenames or sidecars into metadata. |
dateframe inspect |
Inspect a file's available metadata and associated sidecars. |
dateframe extensions |
Count file extensions in a folder or input list. |
Use command-specific help for all options:
dateframe rename --help
dateframe import-icloud --helpdateframe rename uses dates found in embedded metadata and supported sidecars. It keeps associated .xmp and .xml sidecars with renamed media, including Sony-style video XML sidecars:
C0001.MP4 -> 2026-03-02T03-20-52.MP4
C0001M01.XML -> 2026-03-02T03-20-52.MP4.M01.XML
Apple Live Photo image/video pairs are confirmed with embedded identifiers through ExifTool, then renamed to a common timestamp:
IMG_1234.JPG -> 2026-03-02T03-20-52.JPG
IMG_1234.MOV -> 2026-03-02T03-20-52.MOV
The processing commands (import-icloud, rename, and write-dates) write logs to ./logs by default:
- A CSV log records per-file results and is the source used to resume.
- A TXT log records run times, the effective
dateframe <command>invocation, interruption state, and summary counts. - A periodic checkpoint CSV preserves recent progress if a run is interrupted suddenly.
Resume an interrupted run from its most recent CSV or checkpoint:
dateframe rename --resume-csv "./logs/dateframe_rename_2026-05-22T13-37-05.csv"
dateframe import-icloud --resume-csv "./logs/dateframe_import-icloud_2026-05-21T22-54-12_checkpoint.csv"The latest resumed CSV includes previously recorded history, so it becomes the next file to use when continuing. Logs created by earlier versions with legacy script-based names remain valid resume inputs.
There are important differences between iCloud export paths:
dateframe import-icloudoperates on the iCloud Photos folder exposed by the Windows application. It can preserve useful iCloud/Windows date information, but Live Photo video components are not available there when iCloud exposes only the image file.- For
dateframe import-icloud, leave iCloud placeholder files undownloaded when possible: Windows may expose useful iCloud capture dates before a file is downloaded, then replace them after hydration. DateFrame refines minute-only iCloud dates with matching embedded or file timestamp seconds when available. If a cloud download fails after its date was detected, resume from the generated CSV so DateFrame can reuse the preserved date. - Downloads from iCloud Web may provide Live Photos as image and video pairs, which
dateframe renamecan identify and keep together. Some exported files may not contain reliable capture-date metadata.
Extended workflow guidance and findings about iCloud exports, Live Photos, metadata sources, and recovery strategies are good candidates for the project wiki.
DateFrame itself is installed through pip, but some operations require external tools:
| Dependency | Used for |
|---|---|
| ExifTool | Writing metadata and confirming Live Photo pairs. |
| ffmpeg | Reading video metadata. |
| ImageMagick | Image metadata access through Wand. |
dateframe import-icloud is Windows-only because it uses Windows Shell/iCloud metadata through pywin32. The other commands are designed for Windows, Linux, and macOS when their required external tools are available.
If you only use dateframe import-icloud, you need ExifTool but do not need ffmpeg or ImageMagick.
Before running a large import or rename operation, test on a small copied sample and inspect the produced CSV/TXT logs. Logs may contain local file paths, filenames, metadata values, and command arguments; redact private information before sharing them publicly.
Keep an independent backup of important media until you have verified the results.
Bug reports and pull requests are welcome. See CONTRIBUTING.md for development setup and validation guidance.
For security-sensitive reports, see SECURITY.md.
DateFrame is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-only). It may be used commercially, but modified versions made available over a network must also offer their corresponding source code. See LICENSE.md.