OSXPhotos Command Line Interface (CLI)#

osxphotos#

osxphotos: query and export your Photos library

osxphotos [OPTIONS] COMMAND [ARGS]...

Options

--db <PHOTOS_LIBRARY_PATH>#: Specify Photos database path. Path to Photos library/database can be specified using either –db or directly as PHOTOS_LIBRARY positional argument. If neither –db or PHOTOS_LIBRARY provided, will attempt to find the library to use in the following order: 1. last opened library, 2. system library, 3. ~/Pictures/Photos Library.photoslibrary

--json#: Print output in JSON format.

-v, --version#: Show the version and exit.

about#

Print information about osxphotos including license.

osxphotos about [OPTIONS]

albums#

Print out albums found in the Photos library.

osxphotos albums [OPTIONS] [PHOTOS_LIBRARY]...

Options

--db <PHOTOS_LIBRARY_PATH>#: Specify Photos database path. Path to Photos library/database can be specified using either –db or directly as PHOTOS_LIBRARY positional argument. If neither –db or PHOTOS_LIBRARY provided, will attempt to find the library to use in the following order: 1. last opened library, 2. system library, 3. ~/Pictures/Photos Library.photoslibrary

--json#: Print output in JSON format.

Arguments

PHOTOS_LIBRARY#: Optional argument(s)

diff#

Compare two Photos databases and print out differences

To use the diff command, you’ll need to install sqldiff via homebrew:

Install homebrew (https://brew.sh/) if not already installed

Install sqldiff: brew install sqldiff

When run with no arguments, compares the current Photos library to the most recent snapshot in the the OSXPHOTOS_SNAPSHOT directory.

If run with the –db option, compares the library specified by –db to the most recent snapshot in the the OSXPHOTOS_SNAPSHOT directory.

If run with just the DB2 argument, compares the current Photos library to the database specified by the DB2 argument.

If run with both the –db option and the DB2 argument, compares the library specified by –db to the database specified by DB2

docs#

Open osxphotos documentation in your browser.

osxphotos docs [OPTIONS]

dump#

Print list of all photos & associated info from the Photos library.

osxphotos dump [OPTIONS] [PHOTOS_LIBRARY]...

Options

--db <PHOTOS_LIBRARY_PATH>#: Specify Photos database path. Path to Photos library/database can be specified using either –db or directly as PHOTOS_LIBRARY positional argument. If neither –db or PHOTOS_LIBRARY provided, will attempt to find the library to use in the following order: 1. last opened library, 2. system library, 3. ~/Pictures/Photos Library.photoslibrary

--json#: Print output in JSON format.

--deleted#: Include photos from the ‘Recently Deleted’ folder.

--deleted-only#: Include only photos from the ‘Recently Deleted’ folder.

Arguments

PHOTOS_LIBRARY#: Optional argument(s)

exiftool#

Run exiftool on previously exported files to update metadata.

If you previously exported photos with osxphotos export but did not include the –exiftool option and you now want to update the metadata of the exported files with exiftool, you can use this command to do so.

If you simply re-run the osxphotos export with –update and –exiftool, osxphotos will re-export all photos because it will detect that the previously exported photos do not have the exiftool metadata updates. This command will run exiftool on the previously exported photos to update all metadata then will update the export database so that using –exiftool –update with osxphotos export in the future will work correctly and not unnecessarily re-export photos.

osxphotos exiftool [OPTIONS] EXPORT_DIRECTORY

Options

--db-config#: Load configuration options from the export database to match the last export; If any other command line options are used in conjunction with –db-config, they will override the corresponding values loaded from the export database; see also –load-config.

--load-config <CONFIG_FILE>#: Load options from file as written with –save-config. If any other command line options are used in conjunction with –load-config, they will override the corresponding values in the config file; see also –db-config.

--save-config <CONFIG_FILE>#: Save options to file for use with –load-config. File format is TOML.

--exiftool-path <EXIFTOOL_PATH>#: Optionally specify path to exiftool; if not provided, will look for exiftool in $PATH.

--exiftool-option <OPTION>#: Optional flag/option to pass to exiftool when using –exiftool. For example, –exiftool-option ‘-m’ to ignore minor warnings. Specify these as you would on the exiftool command line. See exiftool docs at https://exiftool.org/exiftool_pod.html for full list of options. More than one option may be specified by repeating the option, e.g. –exiftool-option ‘-m’ –exiftool-option ‘-F’.

--exiftool-merge-keywords#: Merge any keywords found in the original file with keywords used for ‘–exiftool’ and ‘–sidecar’.

--exiftool-merge-persons#: Merge any persons found in the original file with persons used for ‘–exiftool’ and ‘–sidecar’.

--ignore-date-modified#: If used with –exiftool or –sidecar, will ignore the photo modification date and set EXIF:ModifyDate to EXIF:DateTimeOriginal; this is consistent with how Photos handles the EXIF:ModifyDate tag.

--person-keyword#: Use person in image as keyword/tag when exporting metadata.

--album-keyword#: Use album name as keyword/tag when exporting metadata.

--keyword-template <TEMPLATE>#: For use with –exiftool, –sidecar; specify a template string to use as keyword in the form ‘{name,DEFAULT}’ This is the same format as –directory. For example, if you wanted to add the full path to the folder and album photo is contained in as a keyword when exporting you could specify –keyword-template “{folder_album}” You may specify more than one template, for example –keyword-template “{folder_album}” –keyword-template “{created.year}”. See ‘–replace-keywords’ and Templating System below.

--replace-keywords#: Replace keywords with any values specified with –keyword-template. By default, –keyword-template will add keywords to any keywords already associated with the photo. If –replace-keywords is specified, values from –keyword-template will replace any existing keywords instead of adding additional keywords.

--description-template <TEMPLATE>#: For use with –exiftool, –sidecar; specify a template string to use as description in the form ‘{name,DEFAULT}’ This is the same format as –directory. For example, if you wanted to append ‘exported with osxphotos on [today’s date]’ to the description, you could specify –description-template “{descr} exported with osxphotos on {today.date}” See Templating System below.

--exportdb <exportdb>#: Optional path to export database (if not in the default location in the export directory).

--report <REPORT_FILE>#: Write a report of all files that were exported. The extension of the report filename will be used to determine the format. Valid extensions are: .csv (CSV file), .json (JSON), .db and .sqlite (SQLite database). REPORT_FILE may be a template string (see Templating System), for example, –report ‘export_{today.date}.csv’ will write a CSV report file named with today’s date. See also –append.

--append#: If used with –report, add data to existing report file instead of overwriting it. See also –report.

-V, --verbose#: Print verbose output.

--timestamp#: Add time stamp to verbose output

--dry-run#: Run in dry-run mode (don’t actually update files), e.g. for use with –update-signatures.

--theme <THEME>#

Specify the color theme to use for –verbose output. Valid themes are ‘dark’, ‘light’, ‘mono’, and ‘plain’. Defaults to ‘dark’ or ‘light’ depending on system dark mode setting.

Options: dark | light | mono | plain

--db <PHOTOS_LIBRARY_PATH>#: Specify Photos database path. Path to Photos library/database can be specified using either –db or directly as PHOTOS_LIBRARY positional argument. If neither –db or PHOTOS_LIBRARY provided, will attempt to find the library to use in the following order: 1. last opened library, 2. system library, 3. ~/Pictures/Photos Library.photoslibrary

Arguments

EXPORT_DIRECTORY#: Required argument

export#

Export photos from the Photos database. Export path DEST is required. Optionally, query the Photos database using 1 or more search options; if more than one option is provided, they are treated as “AND” (e.g. search for photos matching all options). If no query options are provided, all photos will be exported. By default, all versions of all photos will be exported including edited versions, live photo movies, burst photos, and associated raw images. See –skip-edited, –skip-live, –skip-bursts, and –skip-raw options to modify this behavior.

osxphotos export [OPTIONS] [PHOTOS_LIBRARY]... DEST

Options

--db <PHOTOS_LIBRARY_PATH>#: Specify Photos database path. Path to Photos library/database can be specified using either –db or directly as PHOTOS_LIBRARY positional argument. If neither –db or PHOTOS_LIBRARY provided, will attempt to find the library to use in the following order: 1. last opened library, 2. system library, 3. ~/Pictures/Photos Library.photoslibrary

-V, --verbose#: Print verbose output.

--timestamp#: Add time stamp to verbose output

--no-progress#: Do not display progress bar during export.

--keyword <KEYWORD>#: Search for photos with keyword KEYWORD. If more than one keyword, treated as “OR”, e.g. find photos matching any keyword

--no-keyword#: Search for photos with no keyword.

--person <PERSON>#: Search for photos with person PERSON. If more than one person, treated as “OR”, e.g. find photos matching any person

--album <ALBUM>#: Search for photos in album ALBUM. If more than one album, treated as “OR”, e.g. find photos matching any album

--folder <FOLDER>#: Search for photos in an album in folder FOLDER. If more than one folder, treated as “OR”, e.g. find photos in any FOLDER. Only searches top level folders (e.g. does not look at subfolders)

--name <FILENAME>#: Search for photos with filename matching FILENAME. If more than one –name options is specified, they are treated as “OR”, e.g. find photos matching any FILENAME.

--uuid <UUID>#: Search for photos with UUID(s). May be repeated to include multiple UUIDs.

--uuid-from-file <FILE>#: Search for photos with UUID(s) loaded from FILE. Format is a single UUID per line. Lines preceded with # are ignored.

--title <TITLE>#: Search for TITLE in title of photo.

--no-title#: Search for photos with no title.

--description <DESC>#: Search for DESC in description of photo.

--no-description#: Search for photos with no description.

--place <PLACE>#: Search for PLACE in photo’s reverse geolocation info

--no-place#: Search for photos with no associated place name info (no reverse geolocation info)

--location#: Search for photos with associated location info (e.g. GPS coordinates)

--no-location#: Search for photos with no associated location info (e.g. no GPS coordinates)

--label <LABEL>#: Search for photos with image classification label LABEL (Photos 5 only). If more than one label, treated as “OR”, e.g. find photos matching any label

--uti <UTI>#: Search for photos whose uniform type identifier (UTI) matches UTI

-i, --ignore-case#: Case insensitive search for title, description, place, keyword, person, or album.

--edited#: Search for photos that have been edited.

--external-edit#: Search for photos edited in external editor.

--favorite#: Search for photos marked favorite.

--not-favorite#: Search for photos not marked favorite.

--hidden#: Search for photos marked hidden.

--not-hidden#: Search for photos not marked hidden.

--shared#: Search for photos in shared iCloud album (Photos 5 only).

--not-shared#: Search for photos not in shared iCloud album (Photos 5 only).

--burst#: Search for photos that were taken in a burst.

--not-burst#: Search for photos that are not part of a burst.

--live#: Search for Apple live photos

--not-live#: Search for photos that are not Apple live photos.

--portrait#: Search for Apple portrait mode photos.

--not-portrait#: Search for photos that are not Apple portrait mode photos.

--screenshot#: Search for screenshot photos.

--not-screenshot#: Search for photos that are not screenshot photos.

--slow-mo#: Search for slow motion videos.

--not-slow-mo#: Search for photos that are not slow motion videos.

--time-lapse#: Search for time lapse videos.

--not-time-lapse#: Search for photos that are not time lapse videos.

--hdr#: Search for high dynamic range (HDR) photos.

--not-hdr#: Search for photos that are not HDR photos.

--selfie#: Search for selfies (photos taken with front-facing cameras).

--not-selfie#: Search for photos that are not selfies.

--panorama#: Search for panorama photos.

--not-panorama#: Search for photos that are not panoramas.

--has-raw#: Search for photos with both a jpeg and raw version

--only-movies#: Search only for movies (default searches both images and movies).

--only-photos#: Search only for photos/images (default searches both images and movies).

--from-date <from_date>#: Search by item start date, e.g. 2000-01-12T12:00:00, 2001-01-12T12:00:00-07:00, or 2000-12-31 (ISO 8601 with/without timezone).

--to-date <to_date>#: Search by item end date, e.g. 2000-01-12T12:00:00, 2001-01-12T12:00:00-07:00, or 2000-12-31 (ISO 8601 with/without timezone).

--from-time <from_time>#: Search by item start time of day, e.g. 12:00, or 12:00:00.

--to-time <to_time>#: Search by item end time of day, e.g. 12:00 or 12:00:00.

--year <YEAR>#: Search for items from a specific year, e.g. –year 2022 to find all photos from the year 2022. May be repeated to search multiple years.

--added-before <DATE>#: Search for items added to the library before a specific date/time, e.g. –added-before e.g. 2000-01-12T12:00:00, 2001-01-12T12:00:00-07:00, or 2000-12-31 (ISO 8601 with/without timezone).

--added-after <DATE>#: Search for items added to the libray after a specific date/time, e.g. –added-after e.g. 2000-01-12T12:00:00, 2001-01-12T12:00:00-07:00, or 2000-12-31 (ISO 8601 with/without timezone).

--added-in-last <TIME_DELTA>#: Search for items added to the library in the last TIME_DELTA, where TIME_DELTA is a string like ‘12 hrs’, ‘1 day’, ‘1d’, ‘1 week’, ‘2weeks’, ‘1 month’, ‘1 year’. for example, –added-in-last 7d and –added-in-last ‘1 week’ are equivalent. months are assumed to be 30 days and years are assumed to be 365 days. Common English abbreviations are accepted, e.g. d, day, days or m, min, minutes.

--has-comment#: Search for photos that have comments.

--no-comment#: Search for photos with no comments.

--has-likes#: Search for photos that have likes.

--no-likes#: Search for photos with no likes.

--is-reference#: Search for photos that were imported as referenced files (not copied into Photos library).

--not-reference#: Search for photos that are not references, that is, they were copied into the Photos library and are managed by Photos.

--in-album#: Search for photos that are in one or more albums.

--not-in-album#: Search for photos that are not in any albums.

--duplicate#: Search for photos with possible duplicates. osxphotos will compare signatures of photos, evaluating date created, size, height, width, and edited status to find possible duplicates. This does not compare images byte-for-byte nor compare hashes but should find photos imported multiple times or duplicated within Photos.

--min-size <SIZE>#: Search for photos with size >= SIZE bytes. The size evaluated is the photo’s original size (when imported to Photos). Size may be specified as integer bytes or using SI or NIST units. For example, the following are all valid and equivalent sizes: ‘1048576’ ‘1.048576MB’, ‘1 MiB’.

--max-size <SIZE>#: Search for photos with size <= SIZE bytes. The size evaluated is the photo’s original size (when imported to Photos). Size may be specified as integer bytes or using SI or NIST units. For example, the following are all valid and equivalent sizes: ‘1048576’ ‘1.048576MB’, ‘1 MiB’.

--regex <REGEX TEMPLATE>#: Search for photos where TEMPLATE matches regular expression REGEX. For example, to find photos in an album that begins with ‘Beach’: ‘–regex “^Beach” “{album}”’. You may specify more than one regular expression match by repeating ‘–regex’ with different arguments.

--selected#: Filter for photos that are currently selected in Photos.

--exif <EXIF_TAG VALUE>#: Search for photos where EXIF_TAG exists in photo’s EXIF data and contains VALUE. For example, to find photos created by Adobe Photoshop: –exif Software ‘Adobe Photoshop’ `or to find all photos shot on a Canon camera: `–exif Make Canon. EXIF_TAG can be any valid exiftool tag, with or without group name, e.g. EXIF:Make or Make. To use –exif, exiftool must be installed and in the path.

--query-eval <CRITERIA>#: Evaluate CRITERIA to filter photos. CRITERIA will be evaluated in context of the following python list comprehension: photos = [photo for photo in photos if CRITERIA] where photo represents a PhotoInfo object. For example: –query-eval photo.favorite returns all photos that have been favorited and is equivalent to –favorite. You may specify more than one CRITERIA by using –query-eval multiple times. CRITERIA must be a valid python expression. See https://rhettbull.github.io/osxphotos/ for additional documentation on the PhotoInfo class.

--query-function <filename.py::function>#: Run function to filter photos. Use this in format: –query-function filename.py::function where filename.py is a python file you’ve created and function is the name of the function in the python file you want to call. Your function will be passed a list of PhotoInfo objects and is expected to return a filtered list of PhotoInfo objects. You may use more than one function by repeating the –query-function option with a different value. Your query function will be called after all other query options have been evaluated. See https://github.com/RhetTbull/osxphotos/blob/master/examples/query_function.py for example of how to use this option.

--missing#: Export only photos missing from the Photos library; must be used with –download-missing.

--deleted#: Include photos from the ‘Recently Deleted’ folder.

--deleted-only#: Include only photos from the ‘Recently Deleted’ folder.

--update#: Only export new or updated files. See also –force-update and notes below on export and –update.

--force-update#: Only export new or updated files. Unlike –update, –force-update will re-export photos if their metadata has changed even if this would not otherwise trigger an export. See also –update and notes below on export and –update.

--ignore-signature#: When used with ‘–update’, ignores file signature when updating files. This is useful if you have processed or edited exported photos changing the file signature (size & modification date). In this case, ‘–update’ would normally re-export the processed files but with ‘–ignore-signature’, files which exist in the export directory will not be re-exported. If used with ‘–sidecar’, ‘–ignore-signature’ has the following behavior: 1) if the metadata (in Photos) that went into the sidecar did not change, the sidecar will not be updated; 2) if the metadata (in Photos) that went into the sidecar did change, a new sidecar is written but a new image file is not; 3) if a sidecar does not exist for the photo, a sidecar will be written whether or not the photo file was written or updated.

--only-new#: If used with –update, ignores any previously exported files, even if missing from the export folder and only exports new files that haven’t previously been exported.

--limit <LIMIT>#: Export at most LIMIT photos. Useful for testing. May be used with –update to export incrementally.

--dry-run#: Dry run (test) the export but don’t actually export any files; most useful with –verbose.

--export-as-hardlink#: Hardlink files instead of copying them. Cannot be used with –exiftool which creates copies of the files with embedded EXIF data. Note: on APFS volumes, files are cloned when exporting giving many of the same advantages as hardlinks without having to use –export-as-hardlink.

--touch-file#: Sets the file’s modification time to match photo date.

--overwrite#: Overwrite existing files. Default behavior is to add (1), (2), etc to filename if file already exists. Use this with caution as it may create name collisions on export. (e.g. if two files happen to have the same name)

--retry <RETRY>#: Automatically retry export up to RETRY times if an error occurs during export. This may be useful with network drives that experience intermittent errors.

--export-by-date#: Automatically create output folders to organize photos by date created (e.g. DEST/2019/12/20/photoname.jpg).

--skip-edited#: Do not export edited version of photo if an edited version exists.

--skip-original-if-edited#: Do not export original if there is an edited version (exports only the edited version).

--skip-bursts#: Do not export all associated burst images in the library if a photo is a burst photo.

--skip-live#: Do not export the associated live video component of a live photo.

--skip-raw#: Do not export associated RAW image of a RAW+JPEG pair. Note: this does not skip RAW photos if the RAW photo does not have an associated JPEG image (e.g. the RAW file was imported to Photos without a JPEG preview).

--skip-uuid <UUID>#: Skip photos with UUID(s) during export. May be repeated to include multiple UUIDs.

--skip-uuid-from-file <FILE>#: Skip photos with UUID(s) loaded from FILE. Format is a single UUID per line. Lines preceded with # are ignored.

--current-name#: Use photo’s current filename instead of original filename for export. Note: Starting with Photos 5, all photos are renamed upon import. By default, photos are exported with the the original name they had before import.

--convert-to-jpeg#: Convert all non-JPEG images (e.g. RAW, HEIC, PNG, etc) to JPEG upon export. Note: does not convert the RAW component of a RAW+JPEG pair as the associated JPEG image will be exported. You can use –skip-raw to skip exporting the associated RAW image of a RAW+JPEG pair. See also –jpeg-quality and –jpeg-ext. Only works if your Mac has a GPU (thus may not work on virtual machines).

--jpeg-quality <jpeg_quality>#: Value in range 0.0 to 1.0 to use with –convert-to-jpeg. A value of 1.0 specifies best quality, a value of 0.0 specifies maximum compression. Defaults to 1.0

--preview#: Export preview image generated by Photos. This is a lower-resolution image used by Photos to quickly preview the image. See also –preview-suffix and –preview-if-missing.

--preview-if-missing#: Export preview image generated by Photos if the actual photo file is missing from the library. This may be helpful if photos were not copied to the Photos library and the original photo is missing. See also –preview-suffix and –preview.

--preview-suffix <SUFFIX>#: Optional suffix template for naming preview photos. Default name for preview photos is in form ‘photoname_preview.ext’. For example, with ‘–preview-suffix _low_res’, the preview photo would be named ‘photoname_low_res.ext’. The default suffix is ‘_preview’. Multi-value templates (see Templating System) are not permitted with –preview-suffix. See also –preview and –preview-if-missing.

--download-missing#: Attempt to download missing photos from iCloud. The current implementation uses Applescript to interact with Photos to export the photo which will force Photos to download from iCloud if the photo does not exist on disk. This will be slow and will require internet connection. This obviously only works if the Photos library is synched to iCloud. Note: –download-missing does not currently export all burst images; only the primary photo will be exported–associated burst images will be skipped.

--sidecar <FORMAT>#

Create sidecar for each photo exported; valid FORMAT values: xmp, json, exiftool; –sidecar xmp: create XMP sidecar used by Digikam, Adobe Lightroom, etc. The sidecar file is named in format photoname.ext.xmp The XMP sidecar exports the following tags: Description, Title, Keywords/Tags, Subject (set to Keywords + PersonInImage), PersonInImage, CreateDate, ModifyDate, GPSLongitude, Face Regions (Metadata Working Group and Microsoft Photo). –sidecar json: create JSON sidecar useable by exiftool (https://exiftool.org/) The sidecar file can be used to apply metadata to the file with exiftool, for example: “exiftool -j=photoname.jpg.json photoname.jpg” The sidecar file is named in format photoname.ext.json; format includes tag groups (equivalent to running ‘exiftool -G -j’). –sidecar exiftool: create JSON sidecar compatible with output of ‘exiftool -j’. Unlike ‘–sidecar json’, ‘–sidecar exiftool’ does not export tag groups. Sidecar filename is in format photoname.ext.json; For a list of tags exported in the JSON and exiftool sidecar, see ‘–exiftool’. See also ‘–ignore-signature’.

Options: xmp | json | exiftool

--sidecar-drop-ext#: Drop the photo’s extension when naming sidecar files. By default, sidecar files are named in format ‘photo_filename.photo_ext.sidecar_ext’, e.g. ‘IMG_1234.JPG.xmp’. Use ‘–sidecar-drop-ext’ to ignore the photo extension. Resulting sidecar files will have name in format ‘IMG_1234.xmp’. Warning: this may result in sidecar filename collisions if there are files of different types but the same name in the output directory, e.g. ‘IMG_1234.JPG’ and ‘IMG_1234.MOV’.

--exiftool#: Use exiftool to write metadata directly to exported photos. To use this option, exiftool must be installed and in the path. exiftool may be installed from https://exiftool.org/. Cannot be used with –export-as-hardlink. Writes the following metadata: EXIF:ImageDescription, XMP:Description (see also –description-template); XMP:Title; XMP:TagsList, IPTC:Keywords, XMP:Subject (see also –keyword-template, –person-keyword, –album-keyword); XMP:PersonInImage; EXIF:GPSLatitudeRef; EXIF:GPSLongitudeRef; EXIF:GPSLatitude; EXIF:GPSLongitude; EXIF:GPSPosition; EXIF:DateTimeOriginal; EXIF:OffsetTimeOriginal; EXIF:ModifyDate (see –ignore-date-modified); IPTC:DateCreated; IPTC:TimeCreated; (video files only): QuickTime:CreationDate; QuickTime:CreateDate; QuickTime:ModifyDate (see also –ignore-date-modified); QuickTime:GPSCoordinates; UserData:GPSCoordinates.

--exiftool-path <EXIFTOOL_PATH>#: Optionally specify path to exiftool; if not provided, will look for exiftool in $PATH.

--exiftool-option <OPTION>#: Optional flag/option to pass to exiftool when using –exiftool. For example, –exiftool-option ‘-m’ to ignore minor warnings. Specify these as you would on the exiftool command line. See exiftool docs at https://exiftool.org/exiftool_pod.html for full list of options. More than one option may be specified by repeating the option, e.g. –exiftool-option ‘-m’ –exiftool-option ‘-F’.

--exiftool-merge-keywords#: Merge any keywords found in the original file with keywords used for ‘–exiftool’ and ‘–sidecar’.

--exiftool-merge-persons#: Merge any persons found in the original file with persons used for ‘–exiftool’ and ‘–sidecar’.

--favorite-rating#: When used with –exiftool or –sidecar, set XMP:Rating=5 for photos marked as Favorite and XMP:Rating=0 for non-Favorites. If not specified, XMP:Rating is not set.

--ignore-date-modified#: If used with –exiftool or –sidecar, will ignore the photo modification date and set EXIF:ModifyDate to EXIF:DateTimeOriginal; this is consistent with how Photos handles the EXIF:ModifyDate tag.

--person-keyword#: Use person in image as keyword/tag when exporting metadata.

--album-keyword#: Use album name as keyword/tag when exporting metadata.

--keyword-template <TEMPLATE>#: For use with –exiftool, –sidecar; specify a template string to use as keyword in the form ‘{name,DEFAULT}’ This is the same format as –directory. For example, if you wanted to add the full path to the folder and album photo is contained in as a keyword when exporting you could specify –keyword-template “{folder_album}” You may specify more than one template, for example –keyword-template “{folder_album}” –keyword-template “{created.year}”. See ‘–replace-keywords’ and Templating System below.

--replace-keywords#: Replace keywords with any values specified with –keyword-template. By default, –keyword-template will add keywords to any keywords already associated with the photo. If –replace-keywords is specified, values from –keyword-template will replace any existing keywords instead of adding additional keywords.

--description-template <TEMPLATE>#: For use with –exiftool, –sidecar; specify a template string to use as description in the form ‘{name,DEFAULT}’ This is the same format as –directory. For example, if you wanted to append ‘exported with osxphotos on [today’s date]’ to the description, you could specify –description-template “{descr} exported with osxphotos on {today.date}” See Templating System below.

--finder-tag-template <TEMPLATE>#: Set MacOS Finder tags to TEMPLATE. These tags can be searched in the Finder or Spotlight with ‘tag:tagname’ format. For example, ‘–finder-tag-template “{label}”’ to set Finder tags to photo labels. You may specify multiple TEMPLATE values by using ‘–finder-tag-template’ multiple times. See also ‘–finder-tag-keywords and Extended Attributes below.’.

--finder-tag-keywords#: Set MacOS Finder tags to keywords; any keywords specified via ‘–keyword-template’, ‘–person-keyword’, etc. will also be used as Finder tags. See also ‘–finder-tag-template and Extended Attributes below.’.

--xattr-template <ATTRIBUTE TEMPLATE>#: Set extended attribute ATTRIBUTE to TEMPLATE value. Valid attributes are: ‘authors’, ‘comment’, ‘copyright’, ‘creator’, ‘description’, ‘findercomment’, ‘headline’, ‘keywords’, ‘participants’, ‘projects’, ‘rating’, ‘subject’, ‘title’, ‘version’. For example, to set Finder comment to the photo’s title and description: ‘–xattr-template findercomment “{title}; {descr}” See Extended Attributes below for additional details on this option.

--directory <DIRECTORY>#: Optional template for specifying name of output directory in the form ‘{name,DEFAULT}’. See below for additional details on templating system.

--filename <FILENAME>#: Optional template for specifying name of output file in the form ‘{name,DEFAULT}’. File extension will be added automatically–do not include an extension in the FILENAME template. See below for additional details on templating system.

--jpeg-ext <EXTENSION>#

Specify file extension for JPEG files. Photos uses .jpeg for edited images but many images are imported with .jpg or .JPG which can result in multiple different extensions used for JPEG files upon export. Use –jpeg-ext to specify a single extension to use for all exported JPEG images. Valid values are jpeg, jpg, JPEG, JPG; e.g. ‘–jpeg-ext jpg’ to use ‘.jpg’ for all JPEGs.

Options: jpeg | jpg | JPEG | JPG

--strip#: Optionally strip leading and trailing whitespace from any rendered templates. For example, if –filename template is “{title,} {original_name}” and image has no title, resulting file would have a leading space but if used with –strip, this will be removed.

--edited-suffix <SUFFIX>#: Optional suffix template for naming edited photos. Default name for edited photos is in form ‘photoname_edited.ext’. For example, with ‘–edited-suffix _bearbeiten’, the edited photo would be named ‘photoname_bearbeiten.ext’. The default suffix is ‘_edited’. Multi-value templates (see Templating System) are not permitted with –edited-suffix.

--original-suffix <SUFFIX>#: Optional suffix template for naming original photos. Default name for original photos is in form ‘filename.ext’. For example, with ‘–original-suffix _original’, the original photo would be named ‘filename_original.ext’. The default suffix is ‘’ (no suffix). Multi-value templates (see Templating System) are not permitted with –original-suffix.

--use-photos-export#: Force the use of AppleScript or PhotoKit to export even if not missing (see also ‘–download-missing’ and ‘–use-photokit’).

--use-photokit#: Use with ‘–download-missing’ or ‘–use-photos-export’ to use direct Photos interface instead of AppleScript to export. Highly experimental alpha feature; does not work with iTerm2 (use with Terminal.app). This is faster and more reliable than the default AppleScript interface.

--report <REPORT_FILE>#: Write a report of all files that were exported. The extension of the report filename will be used to determine the format. Valid extensions are: .csv (CSV file), .json (JSON), .db and .sqlite (SQLite database). REPORT_FILE may be a template string (see Templating System), for example, –report ‘export_{today.date}.csv’ will write a CSV report file named with today’s date. See also –append.

--append#: If used with –report, add data to existing report file instead of overwriting it. See also –report.

--cleanup#: Cleanup export directory by deleting any files which were not included in this export set. For example, photos which had previously been exported and were subsequently deleted in Photos. WARNING: –cleanup will delete any files in the export directory that were not exported by osxphotos, for example, your own scripts or other files. Be sure this is what you intend before using –cleanup. Use –dry-run with –cleanup first if you’re not certain.

--keep <KEEP_PATH>#: When used with –cleanup, prevents file or directory KEEP_PATH from being deleted when cleanup is run. Use this if there are files in the export directory that you don’t want to be deleted when –cleanup is run. KEEP_PATH may be a file path, e.g. ‘/Volumes/Photos/keep.jpg’, or a file path and wild card, e.g. ‘/Volumes/Photos/.txt’, or a directory, e.g. ‘/Volumes/Photos/KeepMe’. KEEP_PATH may be an absolute path or a relative path. If it is relative, it must be relative to the export destination. For example if export destination is `/Volumes/Photos` and you want to keep all `.txt` files, you can specify `–keep “/Volumes/Photos/.txt”` or –keep “*.txt”. If wild card is used, KEEP_PATH must be enclosed in quotes to prevent the shell from expanding the wildcard, e.g. –keep “/Volumes/Photos/*.txt”. If KEEP_PATH is a directory, all files and directories contained in KEEP_PATH will be kept. –keep may be repeated to keep additional files/directories.

--add-exported-to-album <ALBUM>#: Add all exported photos to album ALBUM in Photos. Album ALBUM will be created if it doesn’t exist. All exported photos will be added to this album. This only works if the Photos library being exported is the last-opened (default) library in Photos. This feature is currently experimental. I don’t know how well it will work on large export sets.

--add-skipped-to-album <ALBUM>#: Add all skipped photos to album ALBUM in Photos. Album ALBUM will be created if it doesn’t exist. All skipped photos will be added to this album. This only works if the Photos library being exported is the last-opened (default) library in Photos. This feature is currently experimental. I don’t know how well it will work on large export sets.

--add-missing-to-album <ALBUM>#: Add all missing photos to album ALBUM in Photos. Album ALBUM will be created if it doesn’t exist. All missing photos will be added to this album. This only works if the Photos library being exported is the last-opened (default) library in Photos. This feature is currently experimental. I don’t know how well it will work on large export sets.

--post-command <CATEGORY COMMAND>#: Run COMMAND on exported files of category CATEGORY. CATEGORY can be one of: exported, new, updated, skipped, missing, exif_updated, touched, converted_to_jpeg, sidecar_json_written, sidecar_json_skipped, sidecar_exiftool_written, sidecar_exiftool_skipped, sidecar_xmp_written, sidecar_xmp_skipped, error. COMMAND is an osxphotos template string, for example: ‘–post-command exported “echo {filepath|shell_quote} >> {export_dir}/exported.txt”’, which appends the full path of all exported files to the file ‘exported.txt’. You can run more than one command by repeating the ‘–post-command’ option with different arguments. See Post Command below.

--post-function <filename.py::function>#: Run function on exported files. Use this in format: –post-function filename.py::function where filename.py is a python file you’ve created and function is the name of the function in the python file you want to call. The function will be passed information about the photo that’s been exported and a list of all exported files associated with the photo. You can run more than one function by repeating the ‘–post-function’ option with different arguments. See Post Function below.

--exportdb <EXPORTDB_FILE>#: Specify alternate path for database file which stores state information for export and –update. If –exportdb is not specified, export database will be saved to ‘.osxphotos_export.db’ in the export directory. If –exportdb is specified, it will be saved to the specified file.

--ramdb#: Copy export database to memory during export; may improve performance when exporting over a network or slow disk but could result in losing update state information if the program is interrupted or crashes.

--tmpdir <DIR>#: Specify alternate temporary directory. Default is system temporary directory. osxphotos needs to create a number of temporary files during export. In some cases, particularly if the Photos library is on an APFS volume that is not the system volume, osxphotos may run faster if you specify a temporary directory on the same volume as the Photos library.

--load-config <CONFIG_FILE>#: Load options from file as written with –save-config. This allows you to save a complex export command to file for later reuse. For example: ‘osxphotos export <lots of options here> –save-config osxphotos.toml’ then ‘osxphotos export /path/to/export –load-config osxphotos.toml’. If any other command line options are used in conjunction with –load-config, they will override the corresponding values in the config file.

--save-config <CONFIG_FILE>#: Save options to file for use with –load-config. File format is TOML. See also –config-only.

--config-only#: If specified, saves the config file but does not export any files; must be used with –save-config.

--theme <THEME>#

Options: dark | light | mono | plain

Arguments

PHOTOS_LIBRARY#: Optional argument(s)

DEST#: Required argument

exportdb#

Utilities for working with the osxphotos export database

osxphotos exportdb [OPTIONS] EXPORT_DATABASE

Options

--version#: Print export database version and exit.

--vacuum#: Run VACUUM to defragment the database.

--check-signatures#: Check signatures for all exported photos in the database to find signatures that don’t match.

--update-signatures#: Update signatures for all exported photos in the database to match on-disk signatures.

--touch-file#: Touch files on disk to match created date in Photos library and update export database signatures

--last-run#: Show last run osxphotos commands used with this database.

--save-config <CONFIG_FILE>#: Save last run configuration to TOML file for use by –load-config.

--info <FILE_PATH>#: Print information about FILE_PATH contained in the database.

--uuid-files <UUID>#: List exported files associated with UUID.

--uuid-info <UUID>#: Print information about UUID contained in the database.

--delete-uuid <UUID>#: Delete all data associated with UUID from the database.

--delete-file <FILE_PATH>#: Delete all data associated with FILE_PATH from the database; does not delete the actual exported file if it exists, only the data in the database.

--report <REPORT_FILE RUN_ID>#: Generate an export report as osxphotos export … –report REPORT_FILE would have done. This allows you to re-create an export report if you didn’t use the –report option when running osxphotos export. The extension of the report file is used to determine the format. Valid extensions are: .csv (CSV file), .json (JSON), .db and .sqlite (SQLite database). RUN_ID may be any integer from -10 to 0 specifying which run to use. For example, –report report.csv 0 will generate a CSV report for the last run and –report report.json -1 will generate a JSON report for the second-to-last run (one run prior to last run). REPORT_FILE may be a template string (see Templating System), for example, –report ‘export_{today.date}.csv’ will write a CSV report file named with today’s date. See also –append.

--migrate#: Migrate (if needed) export database to current version.

--sql <SQL_STATEMENT>#: Execute SQL_STATEMENT against export database and print results.

--export-dir <export_dir>#: Optional path to export directory (if not parent of export database).

--append#: If used with –report, add data to existing report file instead of overwriting it. See also –report.

-V, --verbose#: Print verbose output.

--dry-run#: Run in dry-run mode (don’t actually update files), e.g. for use with –update-signatures.

Arguments

EXPORT_DATABASE#: Required argument

help#

Print help; for help on commands: help <command>.

osxphotos help [OPTIONS] [TOPIC] [SUBTOPIC]

Arguments

TOPIC#: Optional argument

SUBTOPIC#: Optional argument

import#

Import photos and videos into Photos.

osxphotos import [OPTIONS] [FILES]...

Options

-a, --album <ALBUM_TEMPLATE>#: Import photos into album ALBUM_TEMPLATE. ALBUM_TEMPLATE is an osxphotos template string. Photos may be imported into more than one album by repeating –album. See Template System in help for additional information.

-t, --title <TITLE_TEMPLATE>#: Set title of imported photos to TITLE_TEMPLATE. TITLE_TEMPLATE is a an osxphotos template string. See Template System in help for additional information.

-d, --description <DESCRIPTION_TEMPLATE>#: Set description of imported photos to DESCRIPTION_TEMPLATE. DESCRIPTION_TEMPLATE is a an osxphotos template string. See Template System in help for additional information.

-k, --keyword <KEYWORD_TEMPLATE>#: Set keywords of imported photos to KEYWORD_TEMPLATE. KEYWORD_TEMPLATE is a an osxphotos template string. More than one keyword may be set by repeating –keyword. See Template System in help for additional information.

-m, --merge-keywords#: Merge keywords created by –exiftool or –keyword with any keywords already associated with the photo. Without –merge-keywords, existing keywords will be overwritten.

-l, --location <LATITUDE LONGITUDE>#: Set location of imported photo to LATITUDE LONGITUDE. Latitude is a number in the range -90.0 to 90.0; positive latitudes are north of the equator, negative latitudes are south of the equator. Longitude is a number in the range -180.0 to 180.0; positive longitudes are east of the Prime Meridian; negative longitudes are west of the Prime Meridian.

-C, --clear-metadata#: Clear any metadata set automatically by Photos upon import. Normally, Photos will set title, description, and keywords from XMP metadata in the imported file. If you specify –clear-metadata, any metadata set by Photos will be cleared after import.

-L, --clear-location#: Clear any location data automatically imported by Photos. Normally, Photos will set location of the photo to the location data found in the metadata in the imported file. If you specify –clear-location, this data will be cleared after import.

-e, --exiftool#: Use third party tool exiftool (https://exiftool.org/) to automatically update metadata (title, description, keywords, location) in imported photos from the imported file’s metadata. Note: importing keywords from video files is not currently supported.

-p, --exiftool-path <EXIFTOOL_PATH>#: Optionally specify path to exiftool; if not provided, will look for exiftool in $PATH.

-r, --relative-to <RELATIVE_TO_PATH>#: If set, the ‘{filepath}’ template will be computed relative to RELATIVE_TO_PATH. For example, if path to import is ‘/Volumes/photos/import/album/img_1234.jpg’ then ‘{filepath}’ will be this same value. If you set ‘–relative-to /Volumes/photos/import’ then ‘{filepath}’ will be set to ‘album/img_1234.jpg’

-D, --dup-check#: Check for duplicates on import.

-f, --split-folder <split_folder>#: Automatically create hierarchal folders for albums as needed by splitting album name into folders and album. You must specify the character used to split folders and albums. For example, ‘–split-folder “/”’ will split the album name ‘Folder/Album’ into folder ‘Folder’ and album ‘Album’.

-w, --walk#: Recursively walk through directories.

-g, --glob <GLOB>#: Only import files matching GLOB. GLOB is a Unix shell-style glob pattern, for example: ‘–glob “*.jpg”’. GLOB may be repeated to import multiple patterns.

-V, --verbose#: Print verbose output.

-T, --timestamp#: Add time stamp to verbose output

--no-progress#: Do not display progress bar during import.

--check-templates#: Don’t actually import anything; renders template strings so you can verify they are correct.

--theme <THEME>#

Options: dark | light | mono | plain

Arguments

FILES#: Optional argument(s)

info#

Print out descriptive info of the Photos library database.

osxphotos info [OPTIONS] [PHOTOS_LIBRARY]...

Options

--db <PHOTOS_LIBRARY_PATH>#: Specify Photos database path. Path to Photos library/database can be specified using either –db or directly as PHOTOS_LIBRARY positional argument. If neither –db or PHOTOS_LIBRARY provided, will attempt to find the library to use in the following order: 1. last opened library, 2. system library, 3. ~/Pictures/Photos Library.photoslibrary

--json#: Print output in JSON format.

Arguments

PHOTOS_LIBRARY#: Optional argument(s)

inspect#

Interactively inspect photos selected in Photos.

Open Photos then run osxphotos inspect in the terminal. As you select a photo in Photos, inspect will display metadata about the photo. Press Ctrl+C to exit when done. Works best with a modern terminal like iTerm2 or Kitty.

osxphotos inspect [OPTIONS]

Options

-t, --detect-text#: Detect text in photos

-T, --template <TEMPLATE>#: Template string to render for each photo using template preview mode. Useful for testing templates for export; may be repeated to test multiple templates. If –template/-T is used, other inspection data will not be displayed.

--theme <THEME>#

Options: dark | light | mono | plain

--db <PHOTOS_LIBRARY_PATH>#: Specify Photos database path. Path to Photos library/database can be specified using either –db or directly as PHOTOS_LIBRARY positional argument. If neither –db or PHOTOS_LIBRARY provided, will attempt to find the library to use in the following order: 1. last opened library, 2. system library, 3. ~/Pictures/Photos Library.photoslibrary

install#

Install Python packages into the same environment as osxphotos

osxphotos install [OPTIONS] PACKAGES...

Options

-U, --upgrade#: Upgrade packages to latest version

Arguments

PACKAGES#: Required argument(s)

keywords#

Print out keywords found in the Photos library.

osxphotos keywords [OPTIONS] [PHOTOS_LIBRARY]...

Options

--db <PHOTOS_LIBRARY_PATH>#: Specify Photos database path. Path to Photos library/database can be specified using either –db or directly as PHOTOS_LIBRARY positional argument. If neither –db or PHOTOS_LIBRARY provided, will attempt to find the library to use in the following order: 1. last opened library, 2. system library, 3. ~/Pictures/Photos Library.photoslibrary

--json#: Print output in JSON format.

Arguments

PHOTOS_LIBRARY#: Optional argument(s)

labels#

Print out image classification labels found in the Photos library.

osxphotos labels [OPTIONS] [PHOTOS_LIBRARY]...

Options

--db <PHOTOS_LIBRARY_PATH>#: Specify Photos database path. Path to Photos library/database can be specified using either –db or directly as PHOTOS_LIBRARY positional argument. If neither –db or PHOTOS_LIBRARY provided, will attempt to find the library to use in the following order: 1. last opened library, 2. system library, 3. ~/Pictures/Photos Library.photoslibrary

--json#: Print output in JSON format.

Arguments

PHOTOS_LIBRARY#: Optional argument(s)

list#

Print list of Photos libraries found on the system.

osxphotos list [OPTIONS]

Options

--json#: Print output in JSON format.

orphans#

Find orphaned photos in a Photos library

osxphotos orphans [OPTIONS]

Options

--export <EXPORT_PATH>#: Export orphans to directory EXPORT_PATH. If –export not specified, orphans are listed but not exported.

--db <PHOTOS_LIBRARY_PATH>#: Specify Photos database path. Path to Photos library/database can be specified using either –db or directly as PHOTOS_LIBRARY positional argument. If neither –db or PHOTOS_LIBRARY provided, will attempt to find the library to use in the following order: 1. last opened library, 2. system library, 3. ~/Pictures/Photos Library.photoslibrary

-V, --verbose#: Print verbose output.

--timestamp#: Add time stamp to verbose output

--theme <THEME>#

Options: dark | light | mono | plain

persons#

Print out persons (faces) found in the Photos library.

osxphotos persons [OPTIONS] [PHOTOS_LIBRARY]...

Options

--db <PHOTOS_LIBRARY_PATH>#: Specify Photos database path. Path to Photos library/database can be specified using either –db or directly as PHOTOS_LIBRARY positional argument. If neither –db or PHOTOS_LIBRARY provided, will attempt to find the library to use in the following order: 1. last opened library, 2. system library, 3. ~/Pictures/Photos Library.photoslibrary

--json#: Print output in JSON format.

Arguments

PHOTOS_LIBRARY#: Optional argument(s)

places#

Print out places found in the Photos library.

osxphotos places [OPTIONS] [PHOTOS_LIBRARY]...

Options

--db <PHOTOS_LIBRARY_PATH>#: Specify Photos database path. Path to Photos library/database can be specified using either –db or directly as PHOTOS_LIBRARY positional argument. If neither –db or PHOTOS_LIBRARY provided, will attempt to find the library to use in the following order: 1. last opened library, 2. system library, 3. ~/Pictures/Photos Library.photoslibrary

--json#: Print output in JSON format.

Arguments

PHOTOS_LIBRARY#: Optional argument(s)

query#

Query the Photos database using 1 or more search options; if more than one option is provided, they are treated as “AND” (e.g. search for photos matching all options).

osxphotos query [OPTIONS] [PHOTOS_LIBRARY]...

Options

--db <PHOTOS_LIBRARY_PATH>#: Specify Photos database path. Path to Photos library/database can be specified using either –db or directly as PHOTOS_LIBRARY positional argument. If neither –db or PHOTOS_LIBRARY provided, will attempt to find the library to use in the following order: 1. last opened library, 2. system library, 3. ~/Pictures/Photos Library.photoslibrary

--json#: Print output in JSON format.

--keyword <KEYWORD>#: Search for photos with keyword KEYWORD. If more than one keyword, treated as “OR”, e.g. find photos matching any keyword

--no-keyword#: Search for photos with no keyword.

--person <PERSON>#: Search for photos with person PERSON. If more than one person, treated as “OR”, e.g. find photos matching any person

--album <ALBUM>#: Search for photos in album ALBUM. If more than one album, treated as “OR”, e.g. find photos matching any album

--folder <FOLDER>#: Search for photos in an album in folder FOLDER. If more than one folder, treated as “OR”, e.g. find photos in any FOLDER. Only searches top level folders (e.g. does not look at subfolders)

--name <FILENAME>#: Search for photos with filename matching FILENAME. If more than one –name options is specified, they are treated as “OR”, e.g. find photos matching any FILENAME.

--uuid <UUID>#: Search for photos with UUID(s). May be repeated to include multiple UUIDs.

--uuid-from-file <FILE>#: Search for photos with UUID(s) loaded from FILE. Format is a single UUID per line. Lines preceded with # are ignored.

--title <TITLE>#: Search for TITLE in title of photo.

--no-title#: Search for photos with no title.

--description <DESC>#: Search for DESC in description of photo.

--no-description#: Search for photos with no description.

--place <PLACE>#: Search for PLACE in photo’s reverse geolocation info

--no-place#: Search for photos with no associated place name info (no reverse geolocation info)

--location#: Search for photos with associated location info (e.g. GPS coordinates)

--no-location#: Search for photos with no associated location info (e.g. no GPS coordinates)

--label <LABEL>#: Search for photos with image classification label LABEL (Photos 5 only). If more than one label, treated as “OR”, e.g. find photos matching any label

--uti <UTI>#: Search for photos whose uniform type identifier (UTI) matches UTI

-i, --ignore-case#: Case insensitive search for title, description, place, keyword, person, or album.

--edited#: Search for photos that have been edited.

--external-edit#: Search for photos edited in external editor.

--favorite#: Search for photos marked favorite.

--not-favorite#: Search for photos not marked favorite.

--hidden#: Search for photos marked hidden.

--not-hidden#: Search for photos not marked hidden.

--shared#: Search for photos in shared iCloud album (Photos 5 only).

--not-shared#: Search for photos not in shared iCloud album (Photos 5 only).

--burst#: Search for photos that were taken in a burst.

--not-burst#: Search for photos that are not part of a burst.

--live#: Search for Apple live photos

--not-live#: Search for photos that are not Apple live photos.

--portrait#: Search for Apple portrait mode photos.

--not-portrait#: Search for photos that are not Apple portrait mode photos.

--screenshot#: Search for screenshot photos.

--not-screenshot#: Search for photos that are not screenshot photos.

--slow-mo#: Search for slow motion videos.

--not-slow-mo#: Search for photos that are not slow motion videos.

--time-lapse#: Search for time lapse videos.

--not-time-lapse#: Search for photos that are not time lapse videos.

--hdr#: Search for high dynamic range (HDR) photos.

--not-hdr#: Search for photos that are not HDR photos.

--selfie#: Search for selfies (photos taken with front-facing cameras).

--not-selfie#: Search for photos that are not selfies.

--panorama#: Search for panorama photos.

--not-panorama#: Search for photos that are not panoramas.

--has-raw#: Search for photos with both a jpeg and raw version

--only-movies#: Search only for movies (default searches both images and movies).

--only-photos#: Search only for photos/images (default searches both images and movies).

--from-date <from_date>#: Search by item start date, e.g. 2000-01-12T12:00:00, 2001-01-12T12:00:00-07:00, or 2000-12-31 (ISO 8601 with/without timezone).

--to-date <to_date>#: Search by item end date, e.g. 2000-01-12T12:00:00, 2001-01-12T12:00:00-07:00, or 2000-12-31 (ISO 8601 with/without timezone).

--from-time <from_time>#: Search by item start time of day, e.g. 12:00, or 12:00:00.

--to-time <to_time>#: Search by item end time of day, e.g. 12:00 or 12:00:00.

--year <YEAR>#: Search for items from a specific year, e.g. –year 2022 to find all photos from the year 2022. May be repeated to search multiple years.

--added-before <DATE>#: Search for items added to the library before a specific date/time, e.g. –added-before e.g. 2000-01-12T12:00:00, 2001-01-12T12:00:00-07:00, or 2000-12-31 (ISO 8601 with/without timezone).

--added-after <DATE>#: Search for items added to the libray after a specific date/time, e.g. –added-after e.g. 2000-01-12T12:00:00, 2001-01-12T12:00:00-07:00, or 2000-12-31 (ISO 8601 with/without timezone).

--added-in-last <TIME_DELTA>#: Search for items added to the library in the last TIME_DELTA, where TIME_DELTA is a string like ‘12 hrs’, ‘1 day’, ‘1d’, ‘1 week’, ‘2weeks’, ‘1 month’, ‘1 year’. for example, –added-in-last 7d and –added-in-last ‘1 week’ are equivalent. months are assumed to be 30 days and years are assumed to be 365 days. Common English abbreviations are accepted, e.g. d, day, days or m, min, minutes.

--has-comment#: Search for photos that have comments.

--no-comment#: Search for photos with no comments.

--has-likes#: Search for photos that have likes.

--no-likes#: Search for photos with no likes.

--is-reference#: Search for photos that were imported as referenced files (not copied into Photos library).

--not-reference#: Search for photos that are not references, that is, they were copied into the Photos library and are managed by Photos.

--in-album#: Search for photos that are in one or more albums.

--not-in-album#: Search for photos that are not in any albums.

--duplicate#: Search for photos with possible duplicates. osxphotos will compare signatures of photos, evaluating date created, size, height, width, and edited status to find possible duplicates. This does not compare images byte-for-byte nor compare hashes but should find photos imported multiple times or duplicated within Photos.

--min-size <SIZE>#: Search for photos with size >= SIZE bytes. The size evaluated is the photo’s original size (when imported to Photos). Size may be specified as integer bytes or using SI or NIST units. For example, the following are all valid and equivalent sizes: ‘1048576’ ‘1.048576MB’, ‘1 MiB’.

--max-size <SIZE>#: Search for photos with size <= SIZE bytes. The size evaluated is the photo’s original size (when imported to Photos). Size may be specified as integer bytes or using SI or NIST units. For example, the following are all valid and equivalent sizes: ‘1048576’ ‘1.048576MB’, ‘1 MiB’.

--regex <REGEX TEMPLATE>#: Search for photos where TEMPLATE matches regular expression REGEX. For example, to find photos in an album that begins with ‘Beach’: ‘–regex “^Beach” “{album}”’. You may specify more than one regular expression match by repeating ‘–regex’ with different arguments.

--selected#: Filter for photos that are currently selected in Photos.

--exif <EXIF_TAG VALUE>#: Search for photos where EXIF_TAG exists in photo’s EXIF data and contains VALUE. For example, to find photos created by Adobe Photoshop: –exif Software ‘Adobe Photoshop’ `or to find all photos shot on a Canon camera: `–exif Make Canon. EXIF_TAG can be any valid exiftool tag, with or without group name, e.g. EXIF:Make or Make. To use –exif, exiftool must be installed and in the path.

--query-eval <CRITERIA>#: Evaluate CRITERIA to filter photos. CRITERIA will be evaluated in context of the following python list comprehension: photos = [photo for photo in photos if CRITERIA] where photo represents a PhotoInfo object. For example: –query-eval photo.favorite returns all photos that have been favorited and is equivalent to –favorite. You may specify more than one CRITERIA by using –query-eval multiple times. CRITERIA must be a valid python expression. See https://rhettbull.github.io/osxphotos/ for additional documentation on the PhotoInfo class.

--query-function <filename.py::function>#: Run function to filter photos. Use this in format: –query-function filename.py::function where filename.py is a python file you’ve created and function is the name of the function in the python file you want to call. Your function will be passed a list of PhotoInfo objects and is expected to return a filtered list of PhotoInfo objects. You may use more than one function by repeating the –query-function option with a different value. Your query function will be called after all other query options have been evaluated. See https://github.com/RhetTbull/osxphotos/blob/master/examples/query_function.py for example of how to use this option.

--deleted#: Include photos from the ‘Recently Deleted’ folder.

--deleted-only#: Include only photos from the ‘Recently Deleted’ folder.

--missing#: Search for photos missing from disk.

--not-missing#: Search for photos present on disk (e.g. not missing).

--cloudasset#: Search for photos that are part of an iCloud library

--not-cloudasset#: Search for photos that are not part of an iCloud library

--incloud#: Search for photos that are in iCloud (have been synched)

--not-incloud#: Search for photos that are not in iCloud (have not been synched)

--add-to-album <ALBUM>#: Add all photos from query to album ALBUM in Photos. Album ALBUM will be created if it doesn’t exist. All photos in the query results will be added to this album. This only works if the Photos library being queried is the last-opened (default) library in Photos. This feature is currently experimental. I don’t know how well it will work on large query sets.

Arguments

PHOTOS_LIBRARY#: Optional argument(s)

repl#

Run interactive osxphotos REPL shell (useful for debugging, prototyping, and inspecting your Photos library)

osxphotos repl [OPTIONS]

Options

--db <PHOTOS_LIBRARY_PATH>#: Specify Photos database path. Path to Photos library/database can be specified using either –db or directly as PHOTOS_LIBRARY positional argument. If neither –db or PHOTOS_LIBRARY provided, will attempt to find the library to use in the following order: 1. last opened library, 2. system library, 3. ~/Pictures/Photos Library.photoslibrary

--emacs#: Launch REPL with Emacs keybindings (default is vi bindings)

--keyword <KEYWORD>#: Search for photos with keyword KEYWORD. If more than one keyword, treated as “OR”, e.g. find photos matching any keyword

--no-keyword#: Search for photos with no keyword.

--person <PERSON>#: Search for photos with person PERSON. If more than one person, treated as “OR”, e.g. find photos matching any person

--album <ALBUM>#: Search for photos in album ALBUM. If more than one album, treated as “OR”, e.g. find photos matching any album

--folder <FOLDER>#: Search for photos in an album in folder FOLDER. If more than one folder, treated as “OR”, e.g. find photos in any FOLDER. Only searches top level folders (e.g. does not look at subfolders)

--name <FILENAME>#: Search for photos with filename matching FILENAME. If more than one –name options is specified, they are treated as “OR”, e.g. find photos matching any FILENAME.

--uuid <UUID>#: Search for photos with UUID(s). May be repeated to include multiple UUIDs.

--uuid-from-file <FILE>#: Search for photos with UUID(s) loaded from FILE. Format is a single UUID per line. Lines preceded with # are ignored.

--title <TITLE>#: Search for TITLE in title of photo.

--no-title#: Search for photos with no title.

--description <DESC>#: Search for DESC in description of photo.

--no-description#: Search for photos with no description.

--place <PLACE>#: Search for PLACE in photo’s reverse geolocation info

--no-place#: Search for photos with no associated place name info (no reverse geolocation info)

--location#: Search for photos with associated location info (e.g. GPS coordinates)

--no-location#: Search for photos with no associated location info (e.g. no GPS coordinates)

--label <LABEL>#: Search for photos with image classification label LABEL (Photos 5 only). If more than one label, treated as “OR”, e.g. find photos matching any label

--uti <UTI>#: Search for photos whose uniform type identifier (UTI) matches UTI

-i, --ignore-case#: Case insensitive search for title, description, place, keyword, person, or album.

--edited#: Search for photos that have been edited.

--external-edit#: Search for photos edited in external editor.

--favorite#: Search for photos marked favorite.

--not-favorite#: Search for photos not marked favorite.

--hidden#: Search for photos marked hidden.

--not-hidden#: Search for photos not marked hidden.

--shared#: Search for photos in shared iCloud album (Photos 5 only).

--not-shared#: Search for photos not in shared iCloud album (Photos 5 only).

--burst#: Search for photos that were taken in a burst.

--not-burst#: Search for photos that are not part of a burst.

--live#: Search for Apple live photos

--not-live#: Search for photos that are not Apple live photos.

--portrait#: Search for Apple portrait mode photos.

--not-portrait#: Search for photos that are not Apple portrait mode photos.

--screenshot#: Search for screenshot photos.

--not-screenshot#: Search for photos that are not screenshot photos.

--slow-mo#: Search for slow motion videos.

--not-slow-mo#: Search for photos that are not slow motion videos.

--time-lapse#: Search for time lapse videos.

--not-time-lapse#: Search for photos that are not time lapse videos.

--hdr#: Search for high dynamic range (HDR) photos.

--not-hdr#: Search for photos that are not HDR photos.

--selfie#: Search for selfies (photos taken with front-facing cameras).

--not-selfie#: Search for photos that are not selfies.

--panorama#: Search for panorama photos.

--not-panorama#: Search for photos that are not panoramas.

--has-raw#: Search for photos with both a jpeg and raw version

--only-movies#: Search only for movies (default searches both images and movies).

--only-photos#: Search only for photos/images (default searches both images and movies).

--from-date <from_date>#: Search by item start date, e.g. 2000-01-12T12:00:00, 2001-01-12T12:00:00-07:00, or 2000-12-31 (ISO 8601 with/without timezone).

--to-date <to_date>#: Search by item end date, e.g. 2000-01-12T12:00:00, 2001-01-12T12:00:00-07:00, or 2000-12-31 (ISO 8601 with/without timezone).

--from-time <from_time>#: Search by item start time of day, e.g. 12:00, or 12:00:00.

--to-time <to_time>#: Search by item end time of day, e.g. 12:00 or 12:00:00.

--year <YEAR>#: Search for items from a specific year, e.g. –year 2022 to find all photos from the year 2022. May be repeated to search multiple years.

--added-before <DATE>#: Search for items added to the library before a specific date/time, e.g. –added-before e.g. 2000-01-12T12:00:00, 2001-01-12T12:00:00-07:00, or 2000-12-31 (ISO 8601 with/without timezone).

--added-after <DATE>#: Search for items added to the libray after a specific date/time, e.g. –added-after e.g. 2000-01-12T12:00:00, 2001-01-12T12:00:00-07:00, or 2000-12-31 (ISO 8601 with/without timezone).

--added-in-last <TIME_DELTA>#: Search for items added to the library in the last TIME_DELTA, where TIME_DELTA is a string like ‘12 hrs’, ‘1 day’, ‘1d’, ‘1 week’, ‘2weeks’, ‘1 month’, ‘1 year’. for example, –added-in-last 7d and –added-in-last ‘1 week’ are equivalent. months are assumed to be 30 days and years are assumed to be 365 days. Common English abbreviations are accepted, e.g. d, day, days or m, min, minutes.

--has-comment#: Search for photos that have comments.

--no-comment#: Search for photos with no comments.

--has-likes#: Search for photos that have likes.

--no-likes#: Search for photos with no likes.

--is-reference#: Search for photos that were imported as referenced files (not copied into Photos library).

--not-reference#: Search for photos that are not references, that is, they were copied into the Photos library and are managed by Photos.

--in-album#: Search for photos that are in one or more albums.

--not-in-album#: Search for photos that are not in any albums.

--duplicate#: Search for photos with possible duplicates. osxphotos will compare signatures of photos, evaluating date created, size, height, width, and edited status to find possible duplicates. This does not compare images byte-for-byte nor compare hashes but should find photos imported multiple times or duplicated within Photos.

--min-size <SIZE>#: Search for photos with size >= SIZE bytes. The size evaluated is the photo’s original size (when imported to Photos). Size may be specified as integer bytes or using SI or NIST units. For example, the following are all valid and equivalent sizes: ‘1048576’ ‘1.048576MB’, ‘1 MiB’.

--max-size <SIZE>#: Search for photos with size <= SIZE bytes. The size evaluated is the photo’s original size (when imported to Photos). Size may be specified as integer bytes or using SI or NIST units. For example, the following are all valid and equivalent sizes: ‘1048576’ ‘1.048576MB’, ‘1 MiB’.

--regex <REGEX TEMPLATE>#: Search for photos where TEMPLATE matches regular expression REGEX. For example, to find photos in an album that begins with ‘Beach’: ‘–regex “^Beach” “{album}”’. You may specify more than one regular expression match by repeating ‘–regex’ with different arguments.

--selected#: Filter for photos that are currently selected in Photos.

--exif <EXIF_TAG VALUE>#: Search for photos where EXIF_TAG exists in photo’s EXIF data and contains VALUE. For example, to find photos created by Adobe Photoshop: –exif Software ‘Adobe Photoshop’ `or to find all photos shot on a Canon camera: `–exif Make Canon. EXIF_TAG can be any valid exiftool tag, with or without group name, e.g. EXIF:Make or Make. To use –exif, exiftool must be installed and in the path.

--query-eval <CRITERIA>#: Evaluate CRITERIA to filter photos. CRITERIA will be evaluated in context of the following python list comprehension: photos = [photo for photo in photos if CRITERIA] where photo represents a PhotoInfo object. For example: –query-eval photo.favorite returns all photos that have been favorited and is equivalent to –favorite. You may specify more than one CRITERIA by using –query-eval multiple times. CRITERIA must be a valid python expression. See https://rhettbull.github.io/osxphotos/ for additional documentation on the PhotoInfo class.

--query-function <filename.py::function>#: Run function to filter photos. Use this in format: –query-function filename.py::function where filename.py is a python file you’ve created and function is the name of the function in the python file you want to call. Your function will be passed a list of PhotoInfo objects and is expected to return a filtered list of PhotoInfo objects. You may use more than one function by repeating the –query-function option with a different value. Your query function will be called after all other query options have been evaluated. See https://github.com/RhetTbull/osxphotos/blob/master/examples/query_function.py for example of how to use this option.

--deleted#: Include photos from the ‘Recently Deleted’ folder.

--deleted-only#: Include only photos from the ‘Recently Deleted’ folder.

--missing#: Search for photos missing from disk.

--not-missing#: Search for photos present on disk (e.g. not missing).

--cloudasset#: Search for photos that are part of an iCloud library

--not-cloudasset#: Search for photos that are not part of an iCloud library

--incloud#: Search for photos that are in iCloud (have been synched)

--not-incloud#: Search for photos that are not in iCloud (have not been synched)

run#

Run a python file using same environment as osxphotos. Any args are made available to the python file.

osxphotos run [OPTIONS] PYTHON_FILE ARGS

Options

-h, --help#: Show this message and exit

Arguments

PYTHON_FILE#: Required argument

ARGS#: Optional argument(s)

snap#

Create snapshot of Photos database to use with diff command

Snapshots only the database files, not the entire library. If OSXPHOTOS_SNAPSHOT environment variable is defined, will use that as snapshot directory, otherwise uses ‘/private/tmp/osxphotos_snapshots’

Works only on Photos library versions since Catalina (10.15) or newer.

osxphotos snap [OPTIONS]

Options

--db <PHOTOS_LIBRARY_PATH>#: Specify Photos database path. Path to Photos library/database can be specified using either –db or directly as PHOTOS_LIBRARY positional argument. If neither –db or PHOTOS_LIBRARY provided, will attempt to find the library to use in the following order: 1. last opened library, 2. system library, 3. ~/Pictures/Photos Library.photoslibrary

theme#

Manage osxphotos color themes.

osxphotos theme [OPTIONS]

Options

--default#: Show default theme.

--list#: List all themes.

--config <THEME>#: Print configuration for THEME (or default theme if not specified).

--preview <THEME>#: Preview THEME (or default theme if not specified).

--edit <THEME>#: Edit THEME (or default theme if not specified).

--clone <THEME NEW_THEME>#: Clone THEME to NEW_THEME.

--delete <THEME>#: Delete THEME.

timewarp#

Adjust date/time/timezone of photos in Apple Photos.

Changes will be applied to all photos currently selected in Photos. timewarp cannot operate on photos selected in a Smart Album; select photos in a regular album or in the ‘All Photos’ view. See Timewarp Overview below for additional information.

osxphotos timewarp [OPTIONS]

Options

-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 date/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.

-F, --function <filename.py::function>#: Run python function to determine the date/time/timezone to apply to a photo. Use this in format: –function filename.py::function where filename.py is a python file you’ve created and function is the name of the function in the python file you want to call. The function will be passed information about the photo being processed and is expected to return a naive datetime.datetime object with time in local time and UTC timezone offset in seconds. See example function at https://github.com/RhetTbull/osxphotos/blob/master/examples/timewarp_function_example.py

-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 date/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/PhotosLibrary.photoslibrary’). This is not likely needed as osxphotos 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 <exiftool_path>#: Optional path to exiftool executable (will look in $PATH if not specified) for those options which require exiftool.

-o, --output-file <output_file>#: Output file. If not specified, output is written to stdout.

--timestamp#: Add time stamp to verbose output

--theme <THEME>#

Options: dark | light | mono | plain

--plain#: Plain text mode. Do not use rich output.

--force#: Bypass confirmation prompt. Use with caution.

tutorial#

Display osxphotos tutorial.

osxphotos tutorial [OPTIONS] [WIDTH]...

Arguments

WIDTH#: Optional argument(s)

uninstall#

Uninstall Python packages from the osxphotos environment

osxphotos uninstall [OPTIONS] PACKAGES...

Options

-y, --yes#: Don’t ask for confirmation

Arguments

PACKAGES#: Required argument(s)

uuid#

Print out unique IDs (UUID) of photos selected in Photos

Prints outs UUIDs in form suitable for –uuid-from-file and –skip-uuid-from-file

osxphotos uuid [OPTIONS]

Options

-f, --filename#: Include filename of selected photos in output

version#

Check for new version of osxphotos.

osxphotos version [OPTIONS]

Options

--run <COMMAND>#: Run COMMAND if there is a new version of osxphotos available.

Usage: python -m osxphotos [OPTIONS] COMMAND [ARGS]...

Options:
  --db <Photos database path>  Specify Photos database path. Path to Photos
                               library/database can be specified using either
                               --db or directly as PHOTOS_LIBRARY positional
                               argument. If neither --db or PHOTOS_LIBRARY
                               provided, will attempt to find the library to
                               use in the following order: 1. last opened
                               library, 2. system library, 3.
                               ~/Pictures/Photos Library.photoslibrary
  --json                       Print output in JSON format.
  -v, --version                Show the version and exit.
  -h, --help                   Show this message and exit.

Commands:
  about      Print information about osxphotos including license.
  albums     Print out albums found in the Photos library.
  diff       Compare two Photos databases and print out differences
  dump       Print list of all photos & associated info from the Photos...
  export     Export photos from the Photos database.
  help       Print help; for help on commands: help <command>.
  info       Print out descriptive info of the Photos library database.
  install    Install Python packages into the same environment as osxphotos
  keywords   Print out keywords found in the Photos library.
  labels     Print out image classification labels found in the Photos...
  list       Print list of Photos libraries found on the system.
  persons    Print out persons (faces) found in the Photos library.
  places     Print out places found in the Photos library.
  query      Query the Photos database using 1 or more search options; if...
  repl       Run interactive osxphotos REPL shell (useful for debugging,...
  run        Run a python file using same environment as osxphotos
  snap       Create snapshot of Photos database to use with diff command
  theme      Manage osxphotos color themes.
  tutorial   Display osxphotos tutorial.
  uninstall  Uninstall Python packages from the osxphotos environment
  uuid       Print out unique IDs (UUID) of photos selected in Photos