Type something to search...
to navigateto selectESC to close

Apple Photos Import

Import photos from your Apple Photos library

Apple Photos Import

Import photos from your Apple Photos library into Astrolock collections with full metadata.

Info

Requires macOS - This feature uses Apple Photos and is only available on Mac computers.

Quick Start

# Interactive setup (first time)
astrolock import apple-photos --interactive

# Import photos (after setup)
astrolock import apple-photos gallery

How It Works

The interactive wizard will:

  1. List your albums - Shows all albums in Apple Photos
  2. Choose collection - Select which Astrolock collection to import to
  3. Configure settings - Set up image quality, metadata options
  4. Import photos - Exports photos with titles, descriptions, keywords, and locations

All settings are saved to .astrolock/astrolock.yaml, so future imports are quick - just run the command again!

What Gets Imported

Photo Metadata

  • Title - From Apple Photos title field
  • Description - From Apple Photos description
  • Keywords - Converted to tags
  • Date Taken - Original photo date
  • Location - GPS coordinates (if available)

Generated Files

For each photo, Astrolock creates:

src/content/gallery/
  └── 2025-11-28-sunset-beach.md    # Markdown with frontmatter

public/images/gallery/
  └── sunset-beach.jpg               # Optimized image

Example markdown file:

---
title: "Sunset at the Beach"
date: 2025-11-28T18:30:00.000Z
categories:
  - photography
tags:
  - sunset
  - beach
location:
  latitude: 33.7701
  longitude: -118.1937
image: /images/gallery/sunset-beach.jpg
---

A stunning sunset captured at Manhattan Beach.

Configuration Options

Settings are stored in .astrolock/astrolock.yaml under plugins.apple-photos:

plugins:
  apple-photos:
    gallery:
      enabled: true
      album_name: My Portfolio
      source_folder: src/content/gallery
      assets_folder: public/images/gallery
      max_width: 1920
      max_height: 1080
      export_quality: 90
      extract_keywords: true
      extract_location: true
      default_category: photography

Required:

  • album_name - Name of Apple Photos album
  • source_folder - Content folder (e.g., src/content/gallery)
  • assets_folder - Images folder (e.g., public/images/gallery)

Image Settings:

  • export_format - jpeg, png, or original (default: jpeg)
  • export_quality - 1-100 (default: 90)
  • optimize_images - true/false (default: true)
  • max_width - Maximum width in pixels (optional)
  • max_height - Maximum height in pixels (optional)

Metadata:

  • extract_keywords - Import keywords as tags (default: true)
  • extract_location - Import GPS coordinates (default: false)
  • default_category - Category for all photos (optional)
  • default_author - Author attribution (optional)

Sync:

  • overwrite_existing - Update existing photos (default: false)

Step-by-Step Setup

1. Prepare Your Photos

In Apple Photos:

  1. Create an album (e.g., “Portfolio” or “Website Gallery”)
  2. Add photos to the album
  3. Add titles and descriptions to photos (optional but recommended)
  4. Add keywords for tagging (optional)

2. Run Interactive Setup

astrolock import apple-photos --interactive

The wizard will ask:

  • Which album to import from
  • Which collection to import to
  • Image quality and optimization settings
  • Metadata preferences

3. Import Photos

After setup, photos are imported automatically. Future imports:

astrolock import apple-photos gallery

This only imports new photos - existing ones are skipped unless you enable overwrite_existing.

Multiple Collections

You can import different albums to different collections:

# Setup portfolio collection
astrolock import apple-photos --interactive
# Choose "Portfolio" album → "portfolio" collection

# Setup travel collection
astrolock import apple-photos --interactive
# Choose "Travel 2025" album → "travel" collection

# Import both
astrolock import apple-photos portfolio
astrolock import apple-photos travel

Use Cases

Photography Portfolio

Perfect for showcasing your best work:

plugins:
  apple-photos:
    portfolio:
      album_name: Best Work
      max_width: 1920
      extract_keywords: true
      default_category: photography

Travel Blog

Include location data for travel photos:

plugins:
  apple-photos:
    travel:
      album_name: Travel Photos 2025
      extract_location: true
      extract_keywords: true
      default_category: travel

Quick uploads for events:

plugins:
  apple-photos:
    events:
      album_name: Event Photos
      export_quality: 80
      max_width: 1600

Tips

Tip

Organize in Photos First - Set up titles, descriptions, and keywords in Apple Photos before importing. It’s much easier than editing markdown files later!

Tip

Use Albums - Create separate albums for different purposes. Don’t import from “All Photos” - it’s too large!

Tip

Test First - Import a small album first to see the results before importing large collections.

Troubleshooting

Photos Permission Denied

If you see a permission error:

  1. Open System Settings
  2. Go to Privacy & Security → Files and Folders
  3. Find your terminal app (Terminal, iTerm, etc.)
  4. Enable access to Apple Photos
  5. Restart your terminal and try again

Album Not Found

Make sure:

  • Apple Photos is installed and opened at least once
  • You’ve created an album (not just added photos to “All Photos”)
  • The album name matches exactly (case-sensitive)

Photos Taking Too Long

If Photos is slow or times out:

  • Make sure Photos isn’t currently indexing (check Activity Monitor)
  • Close and reopen Apple Photos
  • Try with a smaller album first

Import Skips Photos

By default, existing photos are skipped. To re-import:

plugins:
  apple-photos:
    gallery:
      overwrite_existing: true

See Also