A fast, modern static photo gallery generator with built-in metadata editing.

Check out a live Purtypics gallery or check out our themes.

• Static Generation: Creates fast, self-contained HTML galleries
• Multi-Resolution: Automatically generates multiple image sizes for optimal loading
• Metadata Editor: Built-in web interface for editing photo titles and descriptions
• Video Support: Handles videos with automatic thumbnail generation
• EXIF Data: Extracts and displays camera settings and location data
• Responsive Design: Beautiful masonry layout that works on all devices
• 13 Built-in Themes: From minimal to dramatic — find the right look for your gallery
• Easy Deployment: Deploy to any static host (rsync, S3, Cloudflare Pages)

Album Editor Organize albums with drag-and-drop reordering, cover photos, and descriptions	Photo Editor Edit titles, descriptions, and visibility for individual photos	Gallery Settings Configure title, description, author, theme, and location maps
Rsync Deployment Deploy over SSH with dry-run testing and one-click publish	S3 Deployment Deploy to AWS S3 with connection testing and incremental sync	Cloudflare Pages Deploy to Cloudflare Pages with R2 support for large files

See all platforms on the releases page.

purtypics edit ~/photos --output ./gallery

The --output flag sets where the generated site goes. The editor opens a browser UI where you can organize albums, tag favorites, set cover photos, and choose a theme — no YAML editing required. When everything looks right, click Generate Gallery to build the site, then Deploy to push it live.

The download links above are the quickest way to get started. You can also install from source or via package managers.

git clone https://github.com/chrissnell/purtypics.git
cd purtypics
make build

Purtypics expects your photos to be organized in directories:

~/photos/
├── vacation-2024/
│   ├── IMG_001.jpg
│   ├── IMG_002.jpg
│   └── VIDEO_001.mp4
├── family-reunion/
│   ├── DSC_001.jpg
│   └── DSC_002.jpg
└── gallery.yaml      # Auto-generated metadata file

Each subdirectory becomes an album in your gallery.

The easiest way to set up and generate your gallery is the built-in editor:

purtypics edit ~/photos --output ./gallery

This opens a browser UI where you can:

• Add titles and descriptions to photos
• Mark favorites and hide photos
• Set album cover photos
• Choose a theme from the Gallery Settings tab
• Edit gallery title and description
• Generate your gallery with the Generate Gallery button

All changes are saved to gallery.yaml. When you're happy with everything, click Generate Gallery — the site is built to the --output directory.

You can also generate without the editor:

purtypics generate
purtypics generate -s ~/photos --output ./gallery

This scans for photos and videos, generates optimized thumbnails, and creates the static site.

You can also hand-edit gallery.yaml to customize your gallery:

title: "My Photo Collection"
description: "Family photos and adventures"

albums:
  vacation-2024:
    title: "Summer Vacation 2024"
    description: "Trip to the mountains"
    cover_photo: "IMG_001.jpg"
    
photos:
  vacation-2024/IMG_001.jpg:
    title: "Sunrise at the Summit"
    description: "Early morning hike was worth it!"
    favorite: true

Purtypics ships with 13 built-in themes. Set the theme in gallery.yaml:

theme: darkroom

See the Theme Gallery for screenshots of every theme.

You can also select a theme from the Gallery Settings tab in the editor (purtypics edit).

Create a custom theme by adding a directory under themes/ in your gallery source:

~/photos/
├── vacation-2024/
├── gallery.yaml
└── themes/
    └── mytheme/
        ├── css/
        │   └── gallery.css
        └── templates/       # optional
            ├── base.html
            ├── index.html
            └── album.html

Then set theme: mytheme in gallery.yaml.

A theme only needs to include files you want to override — anything missing falls back to the built-in default. For example, a CSS-only theme just needs css/gallery.css. Look at the default theme as a reference for available template variables and CSS classes.

Theme search order:

1. System-installed — /usr/share/purtypics/themes/ (Linux), /usr/local/share/purtypics/themes/ or /opt/homebrew/share/purtypics/themes/ (macOS), %ProgramData%\Purtypics\themes\ (Windows). Installed by make install or platform packages.
2. Local — themes/ directory alongside your photos
3. Built-in — themes compiled into the binary

Create a deploy.yaml file:

rsync:
  host: user@yourserver.com
  path: /var/www/photos
  port: 22

Then deploy:

purtypics deploy

Deploy to an S3 bucket with incremental sync — only changed files are uploaded and stale files are deleted. Deduplication uses MD5 ETag comparison.

s3:
  bucket: my-photo-gallery
  region: us-east-1
  # Optional settings:
  cloudfront_id: E27EXAMPLE51Z    # invalidate CloudFront cache after deploy
  cache_control: "max-age=31536000"
  storage_class: STANDARD          # STANDARD, STANDARD_IA, GLACIER, etc.
  acl: public-read                 # public-read, private, etc.

AWS credentials are resolved via the standard SDK chain: environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY), ~/.aws/credentials, or IAM role.

purtypics deploy --target s3
purtypics deploy --target s3 --dry-run  # test connection only

Deploy to Cloudflare Pages with hash-based deduplication. Large files (>25 MiB) are automatically uploaded to R2 if enabled.

cloudflare:
  project: my-gallery
  account_id: your-account-id
  auto_create: true               # create project if it doesn't exist
  branch: main                    # optional branch name
  r2:                             # optional: handle files >25 MiB
    enabled: true
    bucket: my-gallery-assets     # defaults to {project}-assets
    custom_domain: assets.example.com

Requires CLOUDFLARE_API_TOKEN environment variable. For R2, also set R2_ACCESS_KEY_ID and R2_SECRET_ACCESS_KEY.

purtypics deploy --target cloudflare

• Original Files: Keep your original photos in a separate backup. Purtypics generates optimized versions.
• Large Collections: For thousands of photos, organize into smaller albums for better performance.
• Video Files: Convert videos to MP4 format for best compatibility.

• Naming: Use descriptive folder names - they become album titles
• Dates: Photos are sorted by EXIF date automatically
• Hidden Files: Files starting with . are ignored

Purtypics generates images in these sizes:

• Small: 300px wide (for thumbnails)
• Medium: 800px wide (for mobile devices)
• Large: 1600px wide (for desktop viewing)
• Full: Original resolution (for downloads)

• Check file extensions: .jpg, .jpeg, .png, .webp, .heif, .heic
• Ensure files aren't hidden (starting with .)
• Verify directory permissions

• Check write permissions on gallery.yaml
• Ensure the editor can access the directory

• Verify SSH access for rsync deployments
• Check credentials in deploy.yaml
• Ensure destination directory exists

Purtypics is designed for private photo collections:

• All processing happens locally on your machine
• No cloud services or external APIs are used
• EXIF location data can be excluded from generated files
• Password protection can be added at the web server level

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

MIT License - See LICENSE for details.