Batch adjust the date, time, or timezone for photos in Apple Photos. Works on macOS only.
Note: All functionality in photos_time_warp has been added to osxphotos as of 1 May 2022. I will no longer be maintaining photos_time_warp and will eventually archive this repository. If you need the functionality in photos_time_warp, I recommend you take a look at osxphotos which offers this same functionality in addition to many other useful tools for working with Photos.
photos_time_warp operates on photos selected in Apple Photos. To use it, open Photos, select the photos for which you'd like to adjust the date/time/timezone, then run photos_time_warp from the command line:
photos_time_warp --date 2021-09-10 --time-delta "-1 hour" --timezone -0700 --verbose
This example sets the date for all selected photos to 2021-09-10, subtracts 1 hour from the time of each photo, and sets the timezone of each photo to GMT -07:00 (Pacific Daylight Time).
photos_time_warp has been well tested on macOS Catalina (10.15). It should work on macOS Big Sur (11.0) and macOS Monterey (12.0) but I have not been able to test this. It will not work on macOS Mojave (10.14) or earlier as the Photos database format is different.
Caution: This app directly modifies your Photos library database using undocumented features. It may corrupt, damage, or destroy your Photos library. Use at your own caution. I strongly recommend you make a backup of your Photos library before using this script (e.g. use Time Machine). See also Warranty.
photos_time_warp --date-delta 1
or
photos_time_warp --date-delta "+1 day"
photos_time_warp --date 2020-04-23 --time-delta "+3 hours"
or
photos_time_warp --date 2020-04-23 --time-delta "+03:00:00"
photos_time_warp --time 14:30 --timezone +01:00
or
photos_time_warp --time 14:30 --timezone +0100
Subtract 1 week from the date for each photo, add 3 hours to the time, set the timezone to UTC -07:00 (Pacific Daylight Time) and also use exiftool to update the EXIF metadata accordingly in the original file; use --verbose to print additional details
photos_time_warp --date-delta "-1 week" --time-delta "+3 hours" --timezone -0700 --push-exif --verbose
For this to work, you'll need to install the third-party exiftool utility. If you use homebrew you can do this with brew install exiftool.
Set the timezone to UTC +03:00 for each photo but keep the time the same (that is, don't adjust time for the new timezone)
photos_time_warp --timezone 0300 --match-time
Note on timezones and times: In Photos, when you change the timezone, Photos assumes the time itself was correct for the previous timezone and adjusts the time accordingly to the new timezone. E.g. if the photo's time is 13:00 and the timezone is GMT -07:00 and you adjust the timezone one hour east to GMT -06:00, Photos will change the time of the photo to 14:00. photos_time_warp follows this behavior. Using --match-time allows you to adjust the timezone but keep the same time without adjustment. For example, if your camera clock was correct but lacked timezone information and you took photos in one timezone but imported them to photos in another, Photos will add the timezone of the computer at time of import. You can use photos_time_warp to adjust the timezone but keep the time using --match-time.
Compare the date/time/timezone of selected photos with the date/time/timezone in the photos' original EXIF metadata
photos_time_warp --compare-exif
I recommend you install photos_time_warp with pipx. The easiest way to do this on a Mac is to use homebrew:
- Open
Terminal(search forTerminalin Spotlight or look inApplications/Utilities) - Install
homebrewaccording to instructions at https://brew.sh/ - Type the following into Terminal:
brew install pipx - Then type this:
pipx install git+https://github.com/RhetTbull/photos_time_warp.git - Now you should be able to run
photos_time_warpby typing:photos_time_warp. - Note: photos_time_warp will also install a shortcut command
ptwthat can be used to start photos_time_warp.
Once you've installed photos_time_warp with pipx, to upgrade to the latest version:
pipx upgrade photos_time_warp
$ photos_time_warp --help
Usage: photos_time_warp [OPTIONS]
photos_time_warp: adjust date/time/timezone of photos in Apple Photos.
Changes will be applied to all photos currently selected in Photos.
photos_time_warp cannot operate on photos selected in a Smart Album; select
photos in a regular album or in the 'All Photos' view.
Specify one or more command: [at least 1 required]
-d, --date DATE Set date for selected photos. Format is 'YYYY-MM-
DD'.
-D, --date-delta DELTA Adjust date for selected photos by DELTA. Format
is one of: '±D days', '±W weeks', '±D' where D is
days
-t, --time TIME Set time for selected photos. Format is one of
'HH:MM:SS', 'HH:MM:SS.fff', 'HH:MM'.
-T, --time-delta DELTA Adjust time for selected photos by DELTA time.
Format is one of '±HH:MM:SS', '±H hours' (or hr),
'±M minutes' (or min), '±S seconds' (or sec),
'±S' (where S is seconds)
-z, --timezone TIMEZONE Set timezone for selected photos as offset from
UTC. Format is one of '±HH:MM', '±H:MM', or
'±HHMM'. The actual time of the photo is not
adjusted which means, somewhat
counterintuitively, that the time in the new
timezone will be different. For example, if photo
has time of 12:00 and timezone of GMT+01:00 and
new timezone is specified as '--timezone +02:00'
(one hour ahead of current GMT+01:00 timezone),
the photo's new time will be 13:00 GMT+02:00,
which is equivalent to the old time of
12:00+01:00. This is the same behavior exhibited
by Photos when manually adjusting timezone in the
Get Info window. See also --match-time.
-i, --inspect Print out the date/time/timezone for each
selected photo without changing any information.
-c, --compare-exif Compare the EXIF date/time/timezone for each
selected photo to the same data in Photos.
Requires the third-party exiftool utility be
installed (see https://exiftool.org/). See also
--add-to-album.
-p, --push-exif Push date/time and timezone for selected photos
from Photos to the EXIF metadata in the original
file in the Photos library. Requires the third-
party exiftool utility be installed (see
https://exiftool.org/). Using this option
modifies the *original* file of the image in your
Photos library. --push-exif will be executed
after any other updates are performed on the
photo. See also --pull-exif.
-P, --pull-exif Pull date/time and timezone for selected photos
from EXIF metadata in the original file into
Photos and update the associated data in Photos
to match the EXIF data. --pull-exif will be
executed before any other updates are performed
on the photo. It is possible for images to have
missing EXIF data, for example the date/time
could be set but there might be no timezone set
in the EXIF metadata. Missing data will be
handled thusly: if date/time/timezone are all
present in the EXIF data, the photo's
date/time/timezone will be updated. If timezone
is missing but date/time is present, only the
photo's date/time will be updated. If date/time
is missing but the timezone is present, only the
photo's timezone will be updated unless --use-
file-time is set in which case, the photo's file
modification time will be used in place of EXIF
date/time. If the date is present but the time is
missing, the time will be set to 00:00:00.
Requires the third-party exiftool utility be
installed (see https://exiftool.org/). See also
--push-exif.
Options:
-m, --match-time When used with --timezone, adjusts the photo time
so that the timestamp in the new timezone matches
the timestamp in the old timezone. For example,
if photo has time of 12:00 and timezone of
GMT+01:00 and new timezone is specified as '--
timezone +02:00' (one hour ahead of current
GMT+01:00 timezone), the photo's new time will be
12:00 GMT+02:00. That is, the timezone will have
changed but the timestamp of the photo will match
the previous timestamp. Use --match-time when the
camera's time was correct for the time the photo
was taken but the timezone was missing or wrong
and you want to adjust the timezone while
preserving the photo's time. See also --timezone.
-f, --use-file-time When used with --pull-exif, the file modification
time will be used if date/time is missing from
the EXIF data.
-a, --add-to-album ALBUM When used with --compare-exif, adds any photos
with date/time/timezone differences between
Photos/EXIF to album ALBUM. If ALBUM does not
exist, it will be created.
-V, --verbose Show verbose output.
-L, --library PHOTOS_LIBRARY_PATH
Path to Photos library (e.g. '~/Pictures/Photos\
Library.photoslibrary'). This is not likely
needed as photos_time_warp will usually be able
to locate the path to the open Photos library.
Use --library only if you get an error that the
Photos library cannot be located.
-e, --exiftool-path PATH Optional path to exiftool executable (will look
in $PATH if not specified) for those options
which require exiftool.
--plain Plain text mode. Do not use rich output.
--mono Monochrome mode. Do not use colored output.
--dark Dark mode. Use dark colors.
--light Light mode. Use light colors.
-o, --output-file FILENAME Output file. If not specified, output is written
to stdout.
Other options:
--version Show the version and exit.
--help Show this message and exit.
photos_time_warp uses colored output which is controlled by the --dark,
--light, --plain, and --mono flags.
If you don't like the default colors you can specify your own by creating a
file named '~/.config/photos_time_warp/colors.cfg'. If this file exists,
photos_time_warp will use the colors specified in this file as the default
colors.
See https://github.com/RhetTbull/photos_time_warp/blob/main/colors.cfg for
sample colors.cfg file.
This app is a bit of a hack. Photos provides a way to change the date and time of a photo using AppleScript but does not provide a way to change the timezone. Date/time adjustments are completed using AppleScript (via python using PhotoScript) and timezone adjustments are done by directly modifying the underlying Photos database (e.g. ~/Pictures/Photos\ Library.photoslibrary/database/Photos.sqlite). Apple does not document the structure of this database--a sqlite database which is actually a CoreData store--so it's possible this script modifies something it shouldn't (or fails to modify something it should) and thus corrupts the database. I've spent considerable time reverse engineering the Photos database for the osxphotos project so I am fairly confident the modifications are safe...but, see the Warranty.
If you want to peek even further under the hood, read on:
Photos maintains a lock on the database, even when Photos is closed, and the python sqlite3 API will not open the database while Photo's maintains its lock. This issue is unique to the python sqlite API; sqlite itself has no problem with this. To get around this limitation, I use a custom sqlite python wrapper that calls the system sqlite library directly using python's python-to-C API. It's very hacky but appears to work OK (at least in my testing on macOS Catalina).
Feedback and contributions of all kinds welcome! Please open an issue if you would like to suggest enhancements or bug fixes.
- osxphotos Export photos and metadata from Apple Photos.
- exif2findertags Read EXIF metadata from image and video files and convert it to macOS Finder tags and/or Finder comments.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Thanks goes to these wonderful people (emoji key):
 John Muccigrosso 🐛 🤔 |
 Thomas K. Running 💻 🐛 |
This project follows the all-contributors specification. Contributions of any kind welcome!
![allcontributors[bot] avatar](https://avatars.githubusercontent.com/in/23186?v=4 "allcontributors[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent