Best Practices

This guide provides recommendations for optimal performance, reliability, and organization when using Immich-Go.

Google Photos Migration

Takeout Creation

✅ Recommended Settings

Format: Choose ZIP format for easier processing
File Size: Select maximum size (50GB) to minimize parts
Content: Include all photos, videos, and metadata
Download: Ensure all parts are downloaded completely

⚠️ Common Pitfalls

Incomplete Downloads: Verify all takeout-001.zip, takeout-002.zip, etc. files are present
Mixed Formats: Don't mix ZIP and TGZ formats in the same import
Partial Takeouts: Some Google takeouts may be incomplete - request a new one if many files are missing

Import Strategy

Large Collections (100k+ Photos)

# Conservative approach for maximum reliability
immich-go upload from-google-photos \
  --server=http://localhost:2283 \
  --api-key=your-api-key \
  --concurrent-tasks=4 \
  --client-timeout=60m \
  --pause-immich-jobs=true \
  --on-errors=continue \
  --session-tag \
  /path/to/takeout-*.zip

Medium Collections (10k-100k Photos)

# Balanced performance and reliability
immich-go upload from-google-photos \
  --server=http://localhost:2283 \
  --api-key=your-api-key \
  --concurrent-tasks=8 \
  --manage-raw-jpeg=StackCoverRaw \
  --manage-burst=Stack \
  /path/to/takeout-*.zip

Small Collections (<10k Photos)

# Fast import with full processing
immich-go upload from-google-photos \
  --server=http://localhost:2283 \
  --api-key=your-api-key \
  --concurrent-tasks=12 \
  --manage-raw-jpeg=StackCoverRaw \
  --manage-burst=Stack \
  --manage-heic-jpeg=StackCoverJPG \
  /path/to/takeout-*.zip

Troubleshooting Import Issues

Many Files Not Imported

Check Takeout Completeness: Verify all parts are included
```
ls -la takeout-*.zip
```

Force Import Unmatched Files:

immich-go upload from-google-photos \
  --include-unmatched \
  --server=... --api-key=... /path/to/takeout-*.zip

Request New Takeout: If data seems incomplete, create a new takeout for missing periods

Resuming Interrupted Imports

Safe to Restart: Immich-Go detects existing files and skips duplicates
Use Session Tags: Enable --session-tag to track what was imported when
Check Logs: Review log files to identify where the import stopped

Performance Optimization

Network Considerations

Gigabit LAN (Fast, Stable)

# High throughput configuration
--concurrent-tasks=16
--client-timeout=30m
--pause-immich-jobs=true

Internet Connection (Variable Speed)

# Adaptive configuration
--concurrent-tasks=4-8
--client-timeout=60m
--on-errors=continue

Slow/Unstable Network

# Conservative configuration
--concurrent-tasks=1-2
--client-timeout=120m
--on-errors=continue

Server Considerations

Powerful Server (High CPU/RAM)

# Maximize server utilization
--concurrent-tasks=12-20
--pause-immich-jobs=false  # Let server handle both
--client-timeout=30m

Limited Server Resources

# Reduce server load
--concurrent-tasks=2-4
--pause-immich-jobs=true
--client-timeout=60m

NAS or Low-Power Server

# Minimal resource usage
--concurrent-tasks=1-2
--pause-immich-jobs=true
--client-timeout=180m

Storage Considerations

Fast Storage (SSD)

Use higher concurrency (8-16 uploads)
Enable all file management features
Process larger batches

Slow Storage (Traditional HDD)

Reduce concurrency (2-4 uploads)
Process smaller batches
Consider staging on faster temporary storage

Network Storage

Account for network latency in timeouts
Test with small batches first
Monitor network utilization

Organization Strategies

Album Management

Folder-Based Albums

# Create albums from folder structure
immich-go upload from-folder \
  --folder-as-album=FOLDER \
  --album-path-joiner=" - " \
  --server=... --api-key=... /organized/photos/

Benefits:

Maintains existing organization
Easy to understand structure
Works well with hierarchical folder systems

Best For: Already organized photo collections

Date-Based Organization

# Let Immich organize by date, use tags for categories
immich-go upload from-folder \
  --tag="Source/Import2024" \
  --tag="Camera/Canon5D" \
  --session-tag \
  --server=... --api-key=... /photos/

Benefits:

Chronological organization
Flexible tagging system
Better for mixed sources

Best For: Large collections from multiple sources

Hybrid Approach

# Combine albums and tags strategically
immich-go upload from-folder \
  --folder-as-album=PATH \
  --folder-as-tags=true \
  --tag="Import/$(date +%Y-%m)" \
  --server=... --api-key=... /photos/

File Management

RAW + JPEG Workflows

Keep Both Separately

--manage-raw-jpeg=NoStack

When to Use: Need both formats accessible, have ample storage

RAW-Centric Workflow

--manage-raw-jpeg=StackCoverRaw

When to Use: Primarily edit RAW files, JPEG for quick preview

JPEG-Centric Workflow

--manage-raw-jpeg=StackCoverJPG

When to Use: Mainly use JPEG, keep RAW as backup

Storage-Conscious

--manage-raw-jpeg=KeepRaw  # Or KeepJPG based on preference

When to Use: Limited storage, need to choose one format

Burst Photo Management

Creative Photography

--manage-burst=Stack

Benefits: Keeps all shots while reducing clutter

Casual Photography

--manage-burst=StackKeepJPEG

Benefits: Saves storage, keeps most useful format

Professional Photography

--manage-burst=NoStack

Benefits: Full access to all shots for selection

Tagging Strategies

Hierarchical Tagging

# Geographic hierarchy
--tag="Location/Europe/France/Paris"

# Event hierarchy  
--tag="Events/2024/Wedding/Ceremony"

# Equipment hierarchy
--tag="Equipment/Camera/Canon/5D-Mark-IV"

Multi-Dimensional Tagging

# Combine multiple tag dimensions
--tag="Location/Paris" \
--tag="Event/Wedding" \
--tag="People/Family" \
--tag="Year/2024"

Source Tracking

# Always tag sources for future reference
--tag="Source/GooglePhotos" \
--tag="Import/$(date +%Y-%m-%d)" \
--session-tag

Backup and Recovery

Backup Strategies

3-2-1 Backup Rule

3 Copies: Original + 2 backups
2 Different Media: Local + cloud/external
1 Offsite: Cloud or remote location

Implementation Example

# Local backup (Copy 2)
immich-go archive from-immich \
  --server=http://localhost:2283 \
  --api-key=your-api-key \
  --write-to-folder=/local-backup/immich

# Offsite backup (Copy 3) - sync local backup to cloud
rsync -av /local-backup/immich/ user@remote-server:/backups/immich/

Incremental Backups

#!/bin/bash
# Daily incremental backup script

YESTERDAY=$(date -d '1 day ago' '+%Y-%m-%d')
TODAY=$(date '+%Y-%m-%d')

immich-go archive from-immich \
  --server=http://localhost:2283 \
  --api-key=your-api-key \
  --from-date-range="$YESTERDAY,$TODAY" \
  --write-to-folder="/backup/incremental/$TODAY"

Full Periodic Backups

# Monthly full backup
immich-go archive from-immich \
  --server=http://localhost:2283 \
  --api-key=your-api-key \
  --write-to-folder="/backup/full/$(date +%Y-%m)"

Testing and Validation

Pre-Migration Testing

# Test with small subset first
immich-go upload from-folder \
  --dry-run \
  --log-level=DEBUG \
  --server=... --api-key=... /small-test-folder/

Backup Validation

# Test restore capability
immich-go upload from-folder \
  --server=http://test-server:2283 \
  --api-key=test-api-key \
  /backup/folder/2024/2024-01/

Security and Privacy

API Key Management

✅ Best Practices

Separate Keys: Use different API keys for different purposes
Minimal Permissions: Only grant necessary permissions
Regular Rotation: Rotate keys periodically
Secure Storage: Don't hardcode keys in scripts

Example Key Strategy

# Different keys for different operations
UPLOAD_KEY="key-with-upload-permissions"
BACKUP_KEY="key-with-read-only-permissions"
ADMIN_KEY="key-with-admin-permissions"

# Upload operations
immich-go upload from-folder --api-key="$UPLOAD_KEY" ...

# Backup operations  
immich-go archive from-immich --api-key="$BACKUP_KEY" ...

Script Security

#!/bin/bash
# Secure script example

# Read API key from secure file
API_KEY=$(cat ~/.config/immich-go/api-key)
chmod 600 ~/.config/immich-go/api-key  # Restrict permissions

# Or use environment variable
export IMMICH_API_KEY="your-key"
immich-go upload from-folder --api-key="$IMMICH_API_KEY" ...

Network Security

SSL/TLS Configuration

# Always use HTTPS in production
immich-go upload from-folder \
  --server=https://immich.yourdomain.com \
  --api-key=your-key \
  /photos/

# Only use --skip-verify-ssl for testing/development
immich-go upload from-folder \
  --server=https://immich-dev.local \
  --skip-verify-ssl \  # Only for self-signed certs in dev
  --api-key=your-key \
  /photos/

Network Isolation

VPN Access: Access Immich server through VPN when possible
Firewall Rules: Restrict Immich server access to specific networks
Reverse Proxy: Use reverse proxy with proper SSL termination

Monitoring and Troubleshooting

Logging Strategy

Development/Testing

--log-level=DEBUG \
--log-file=/tmp/immich-go-debug.log \
--api-trace

Production Operations

--log-level=INFO \
--log-file=/var/log/immich-go/upload-$(date +%Y%m%d).log

Automated Operations

--log-level=WARN \
--log-file=/var/log/immich-go/automated.log \
--no-ui

Health Monitoring

Upload Progress Tracking

# Monitor upload with session tags
immich-go upload from-folder \
  --session-tag \
  --tag="Batch/$(date +%Y%m%d-%H%M)" \
  --server=... --api-key=... /photos/

Storage Monitoring

# Check available space before large operations
df -h /immich-storage
df -h /temp-directory

# Monitor during operation
watch df -h /immich-storage

Server Performance

# Monitor server resources during upload
htop
iotop
nethogs

Error Recovery

Handling Upload Failures

# Continue on errors, log issues
immich-go upload from-folder \
  --on-errors=continue \
  --log-level=INFO \
  --log-file=/var/log/errors.log \
  --server=... --api-key=... /photos/

# Review errors later
grep "ERROR" /var/log/errors.log

Network Interruption Recovery

# Restart with same parameters - Immich-Go handles duplicates
immich-go upload from-folder \
  --server=... --api-key=... /photos/

Partial Import Recovery

# Use session tags to identify what was processed
immich-go upload from-folder \
  --session-tag \
  --server=... --api-key=... /remaining-photos/

Migration Planning

Pre-Migration Checklist

✅ Requirements

Immich server properly configured and accessible
API key created with all necessary permissions
Sufficient storage space (estimate 1.5x source size)
Network capacity planned (estimate transfer time)
Backup of source data created

✅ Testing

Test with small subset of photos
Verify upload quality and metadata preservation
Test backup/restore procedures
Validate performance with expected load

✅ Preparation

Clean up source data (remove unwanted files)
Organize source structure if needed
Plan migration schedule (off-peak hours)
Prepare monitoring and logging

Migration Execution

Phase 1: Test Migration

# Small test batch
immich-go upload from-folder \
  --dry-run \
  --server=... --api-key=... /test-photos/

Phase 2: Pilot Migration

# Subset of real data
immich-go upload from-folder \
  --session-tag \
  --tag="Migration/Pilot" \
  --server=... --api-key=... /pilot-batch/

Phase 3: Full Migration

# Complete migration with monitoring
immich-go upload from-google-photos \
  --session-tag \
  --tag="Migration/Full" \
  --concurrent-tasks=8 \
  --log-file=/var/log/migration.log \
  --server=... --api-key=... /takeout-*.zip

Post-Migration

Validation Steps

Count Verification: Compare source and destination counts
Spot Checks: Verify random samples for quality
Metadata Check: Ensure dates, locations, albums preserved
Organization Review: Confirm albums and tags applied correctly

Cleanup

# Archive original source data after validation
tar -czf google-photos-backup.tar.gz takeout-*.zip
mv google-photos-backup.tar.gz /secure-archive/

# Clean up temporary files
rm -rf /temp/immich-go-*

Uh oh!

FilesExpand file tree

best-practices.md

Latest commit

History