photos_time_warp

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.

Examples

Add 1 day to the date of each photo

photos_time_warp --date-delta 1

or

photos_time_warp --date-delta "+1 day"

Set the date of each photo to 23 April 2020 and add 3 hours to the time

photos_time_warp --date 2020-04-23 --time-delta "+3 hours"

or

photos_time_warp --date 2020-04-23 --time-delta "+03:00:00"

Set the time of each photo to 14:30 and set the timezone to UTC +1:00 (Central European Time)

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

Installation

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 for Terminal in Spotlight or look in Applications/Utilities)
• Install homebrew according 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_warp by typing: photos_time_warp.
• Note: photos_time_warp will also install a shortcut command ptw that 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

Usage

$ 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.

Implementation Details

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).

Contributing

Feedback and contributions of all kinds welcome! Please open an issue if you would like to suggest enhancements or bug fixes.

Related Projects

• 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.

Warranty

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.

Contributors ✨

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!