xomoxcc/flickr-download repository overview

⁠Flickr Download (Docker)

A Docker image for backing up Flickr photo libraries using flickr_download⁠ with browser-based OAuth authentication. Based on python:3.14-slim, available for linux/amd64 and linux/arm64. Source on GitHub⁠.

⁠Screenshots

⁠Why this is useful

• Browser-based OAuth in a container — X11 forwarding, Unix domain socket, or D-Bus portal modes let the Flickr OAuth browser flow work from inside a container without manual token wrangling.
• Rate-limit handling — a wrapper process detects HTTP 429 responses, freezes flickr_download with SIGSTOP, backs off exponentially, then resumes with SIGCONT. No photos are silently skipped.
• ExifTool metadata — downloaded photos retain their original EXIF data; JSON metadata is saved alongside each file.
• Resumable downloads — API response caching means interrupted downloads pick up where they left off.
• Patched flickr_download — installed from GitHub (not PyPI) for unreleased fixes; photos with unknown dates (0000-00-00) are gracefully skipped instead of crashing.

⁠What's inside

⁠Key files

⁠Installed packages

Chromium, Firefox ESR, ExifTool (libimage-exiftool-perl), X11 libraries, D-Bus / gdbus, flickr_download (from GitHub HEAD).

⁠Quick start

# Pull the image
docker pull xomoxcc/flickr-download:latest

# Authenticate (opens browser for OAuth, prompts for API key on first run)
docker run --rm -it \
  -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix \
  -v "$(pwd)/flickr-config:/root" \
  xomoxcc/flickr-download:latest auth

# Download all albums for a Flickr user
docker run --rm -it \
  -v "$(pwd)/flickr-config:/root" \
  -v "$(pwd)/flickr-backup:/root/flickr-backup" \
  -v "$(pwd)/flickr-cache:/root/flickr-cache" \
  xomoxcc/flickr-download:latest download <user>

⁠Commands

⁠Browser modes

The OAuth flow needs a browser. Three modes are supported on Linux; Mac/Windows print the URL for manual opening.

The modes are mutually exclusive.

⁠Rate-limit backoff

flickr_download has no built-in retry for 429 Too Many Requests. The wrapper detects these responses, freezes the process with SIGSTOP, sleeps with increasing backoff, then sends SIGCONT to resume.

⁠Dry-run mode

--dry-run connects to the Flickr API and lists what would be downloaded without actually downloading any files or creating any directories.

# List all albums with photo/video counts
docker run --rm -it \
  -v "$(pwd)/flickr-config:/root" \
  xomoxcc/flickr-download:latest download <user> --dry-run

# Also list individual photos per album
docker run --rm -it \
  -v "$(pwd)/flickr-config:/root" \
  xomoxcc/flickr-download:latest download <user> --dry-run --verbose

# List photos in a single album
docker run --rm -it \
  -v "$(pwd)/flickr-config:/root" \
  xomoxcc/flickr-download:latest album <id> --dry-run

Adding --verbose (or -v) to download --dry-run lists every photo/video per album. album --dry-run always lists individual photos. The download_then_upload entrypoint also supports --dry-run.

⁠Immich upload

upload-to-immich.sh uploads downloaded photos and videos to an Immich⁠ instance, creating one Immich album per Flickr album directory. It uses @immich/cli (installed at runtime via npm).

When running inside a container (/.dockerenv, /run/.containerenv, or KUBERNETES_SERVICE_HOST detected), the script runs @immich/cli directly. On the host it spins up a node:lts-alpine Podman container with the photo directory mounted read-only.

IMMICH_INSTANCE_URL=https://immich.example.com IMMICH_API_KEY=secret ./upload-to-immich.sh

Supported file types: .jpg, .png, .mp4.

⁠Podman notes

When Podman is detected the wrapper script automatically adds --userns=keep-id and --security-opt label=disable. Running the published image directly:

podman run --rm -it --userns=keep-id \
  -e "HOME=/home/poduser" \
  -v "$(pwd)/flickr-config:/home/poduser" \
  -v "$(pwd)/flickr-backup:/home/poduser/flickr-backup" \
  -v "$(pwd)/flickr-cache:/home/poduser/flickr-cache" \
  docker.io/xomoxcc/flickr-download:latest list <user>

⁠Data directories

⁠Build from source

./build_multiarch.sh              # build and push to Docker Hub (amd64 + arm64)
./build_multiarch.sh onlylocal    # local build only (no push)

⁠Credentials

The build script sources scripts/include.sh, which loads scripts/include.local.sh (not committed) for Docker Hub credentials. See the repository root for details.

⁠License

See the repository's license files in the project root (LICENSE.md, LICENSEMIT.md, etc.).

⁠⚠️ Note

This is a development/experimental project. For production use, review security settings, customize configurations, and test thoroughly in your environment. Provided "as is" without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software. Use at your own risk.