Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/haukesomm/apple-photos-export
Command line tool to export photos from the macOS Photos library, organized by album and/or date.
https://github.com/haukesomm/apple-photos-export
apple-photos-export cli homebrew macos reverse-engineering rust rust-cli sqlite3
Last synced: 2 months ago
JSON representation
Command line tool to export photos from the macOS Photos library, organized by album and/or date.
- Host: GitHub
- URL: https://github.com/haukesomm/apple-photos-export
- Owner: haukesomm
- License: mit
- Created: 2024-02-23T20:32:59.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2024-09-17T11:26:18.000Z (3 months ago)
- Last Synced: 2024-10-05T10:23:16.684Z (3 months ago)
- Topics: apple-photos-export, cli, homebrew, macos, reverse-engineering, rust, rust-cli, sqlite3
- Language: Rust
- Homepage:
- Size: 88.9 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# apple-photos-export
This program exports all images and videos from an Apple Photos Library to a local directory, making the files easily
accessible without the need to use the native Photos app.
It is intended for backup purposes and does not modify the library in any way.
> [!IMPORTANT]
> The project works by reverse-engineering the Apple Photos Library database and file structure. Thus, it is not
> guaranteed to work with future versions of the Photos app or at all. Use it at your own risk and always keep a backup
> of your library.
## Highlights
- Lists all albums of the library as an ascii tree
- Exports all images and videos from the Photos Library to a local directory
- Different export album structures are supported (overview below)
- Flat (default)
- Album
- Year/Month
- Year/Month/Album
- Optionally restores the original file names that were used when importing the files into the library
- Dry-run mode to test the export without actually copying any files
## Compatibility
> [!NOTE]
> Currently, each version of this app only works with a sepcific combination of macOS and the Photos app.
> Backwards compatibility to older versions is planned for future releases.
The following versions of the app are compatible with the following macOS/PhotosLibrary version:
| App version | macOS Name | macOS Version | Photos Version | Notes |
|:--------------------------|:-----------|:----------------|:---------------|:---------------------------------------------------------------------------------------------------------------|
| `0.4.0-SNAPSHOT` | Sequoia | `15.0` | `10.0` | |
| `0.3.0` | Sonoma | `14.6` | `9.0` | The internal schema of the Photos app has changed, making this release incompatible with other Sonoma releases |
| `0.2.0`, `0.1.0`, `0.0.1` | Sonoma | `14.0` - `14.5` | `9.0 ` | |
## Changelog
For an overview of the changes made between each version, please have a look at the [CHANGELOG](CHANGELOG.md).
## Usage
### Building and Running locally
```shell
$ cargo build --release
$ ./target/release/apple-photos-export --help
```
### Installation via Homebrew
```shell
$ brew install haukesomm/repo/apple-photos-export
```
OR
```shell
$ brew tap haukesomm/repo
$ brew install apple-photos-export
```
### Listing albums
```shell
$ apple-photos-export list-albums
```
### Exporting assets
```shell
$ apple-photos-export export [OPTIONS]
```
Configuration options
```
-a, --by-album Group assets by album
-m, --by-year-month Group assets by year/month
-M, --by-year-month-album Group assets by year/month/album
-i, --include-albums [...] Include assets in the albums matching the given ids
-x, --exclude-albums ... Exclude assets in the albums matching the given ids
-H, --include-hidden Include hidden assets
--must-be-hidden Assets must be hidden
-r, --restore-original-filenames Restore original filenames
-f, --flatten-albums Flatten album structure
-e, --include-edited Include edited versions of the assets if available
-E, --only-edited Always export the edited version of an asset if available
-d, --dry-run Dry run
-h, --help Print help
```
#### Examples
The following snippets show as an example how to export assets from a Photos Library and may be used as a starting
point.
> [!IMPORTANT]
> Remember to test the different configuration options using the `-d` flag (dry-run) before running any actual exports!
Snippets
##### Full export
- Exports everything, including hidden assets
- Restores the original filenames used when importing the assets to the library
- Groups the assets in a `Year/Month/Album` structure
- Includes both the original and edited versions of each asset
```shell
$ apple-photos-export export -MHrfe
```
##### Only include assets from a list of specific albums
- Exports all assets that _are_ part of any of the given albums (in this case `700` and `701`)
- Album IDs can be obtained via the `list-albums` command
```shell
$ apple-photos-export export -i 700 701
```
##### Exclude all assets being in a list of specific albums
- Exports all assets that _are not_ part of any of the given albums (in this case `700` and `701`)
- Album IDs can be obtained via the `list-albums` command
```shell
$ apple-photos-export export -x 700 701
```
##### Export hidden files only
- Exports all _hidden_ assets
```shell
$ apple-photos-export export [library_path] [output_path] --must-be-hidden
```