pix

Batch AVIF shrink and image-host sync CLI.

pix incrementally compresses local image directories to AVIF, mirrors originals to cloud storage, and publishes compressed images to an image host. Compression uses pyvips; sync is delegated to rclone.

中文 · Architecture · Development · Decisions · Roadmap

Status: core commands are implemented and tested. Real R2 and Windows smoke tests are still pending; see the roadmap.

What pix does

pix is deliberately narrow:

• It is not an rclone replacement and does not manage credentials.
• It does not read repository config or care about version control.
• It has no one-shot pix run; you chain the commands yourself.

How it works

photos/ ── shrink (pyvips) ──> out/*.avif + out/.pix/state.json
                                     │
                                     └── publish (rclone bisync) ──> r2:images
photos/ ── mirror (rclone bisync) ────────────────────────────────> onedrive:photos

Sync is rclone. mirror and publish only compose rclone bisync arguments; rclone handles authentication, transfers and conflict handling. Configure remotes with rclone config before using them. pix never reads or writes rclone.conf.

mirror / publish are bidirectional mirrors, not one-way copies. Deletions propagate in both directions.

Requirements

• Python 3.11+
• uv
• rclone >= 1.66 for mirror / publish (and for pix doctor to report a clean environment)
• At least one remote already configured in rclone

pyvips[binary] bundles libvips, so no separate vips installation is required.

Install

Install from PyPI:

uv tool install pix-cli
pix --version

Upgrade with uv tool upgrade pix-cli; remove with uv tool uninstall pix-cli. Linux installs ~/.local/bin/pix; Windows installs %USERPROFILE%\.local\bin\pix.exe.

To work on pix itself, install the checkout in editable mode:

git clone https://github.com/uzvg/pix.git
cd pix
uv tool install --editable .
pix --version

An editable install picks up source changes immediately. Reinstall with uv tool install --force --editable ..

Configure rclone

Only needed for mirror / publish:

rclone config         # create a remote, for example onedrive or r2
rclone lsd onedrive:  # verify that it works

rclone stores credentials in ~/.config/rclone/rclone.conf (Windows: %APPDATA%\rclone\rclone.conf). pix passes the remote name through and does not store or validate credentials.

Configure pix (optional)

Default configuration paths:

• Linux/macOS: $XDG_CONFIG_HOME/pix/config.toml, or ~/.config/pix/config.toml
• Windows: %APPDATA%\pix\config.toml

If the file is missing, built-in defaults are used. Generate a commented file with:

pix config init

Existing files are not overwritten; pass --force to replace one. Use --config PATH before the subcommand to point at another file; an explicit path must exist, while a missing default path is fine.

Common keys:

Precedence is command line > pix config > built-in defaults. --exclude is appended to config excludes rather than replacing them. -q means quality; --quiet is errors-only; -v / --verbose adds per-file detail and rclone progress. --no-urls overrides [publish].urls = true for one run.

The default [mirror].include is jpg, jpeg, png, webp, gif, bmp, tif, tiff, heic, heif, avif, jxl, svg, ico, cr2, cr3, nef, arw, dng, orf, raf, rw2. Set it to [] to mirror every file.

Quick start

1. Check the environment:

   pix doctor
   

2. Compress images:

   pix shrink -s ~/Pictures -d ~/Pictures-avif --dry-run
   pix shrink -s ~/Pictures -d ~/Pictures-avif -w 1920 -q 85
   

   The first run encodes everything; later runs skip unchanged files. State lives in OUT/.pix/state.json. -w is a maximum long edge, so smaller images are not upscaled; relative directories are preserved under OUT. Change detection uses source size/mtime and output size, not content hashes. Changing width, quality or effort triggers a full re-encode. --dry-run only prints the plan. --prune removes only outputs recorded in state; extra files in OUT are left alone.

3. Mirror originals:

   pix mirror -s ~/Pictures -d onedrive:photos --dry-run
   pix mirror -s ~/Pictures -d onedrive:photos
   

   The destination is created automatically. Only files matching [mirror].include are mirrored; other source files are ignored, and non-matching files already on the destination are left untouched. If no source file matches the filter, the source counts as empty and is refused unless you pass --allow-empty --resync. An empty destination initializes its own baseline, so no --resync is needed on the first run. Use --resync to rebuild the baseline when the destination already has matching content, or after changing include/exclude; --dry-run may create an empty destination but does not transfer or delete. After upgrading from a version without include filtering, the first run also needs --resync; preview with --dry-run --resync first (the preview does not write the baseline).

4. Publish the AVIF output:

   pix publish -s ~/Pictures-avif -d r2:images \
     --base-url https://img.example.com --urls > urls.json
   

   publish requires at least one .avif in the source unless you pass --allow-empty --resync; it syncs only .avif files and always excludes .pix/**. The URL manifest is printed to stdout as JSON only after a successful, non-dry-run sync. It lists every .avif under OUT, not just files changed in this run, and is not filtered by [publish].exclude or --exclude; excluded files can still appear in it. If you rely on excludes to hide files, do not publish the manifest until this behavior is fixed.

5. Re-run later:

   pix shrink -s ~/Pictures -d ~/Pictures-avif
   pix mirror -s ~/Pictures -d onedrive:photos
   pix publish -s ~/Pictures-avif -d r2:images \
     --base-url https://img.example.com --urls
   

   Only changes are encoded and transferred. --base-url is not persisted between runs; set [publish].base_url in config to avoid repeating it.

Command cheat sheet

Safety rules

Output and exit codes

• Logs and progress go to stderr.
• stdout carries doctor reports, shrink --dry-run plans, config init's wrote <path>, and --urls JSON. mirror / publish --dry-run output comes from rclone.
• Exit codes: 0 success, 1 runtime failure, 2 argument or configuration error.
• mirror / publish return rclone's bisync exit code unchanged; destination preflight failures return 1.

URL manifest example:

{
  "2024/a.avif": "https://img.example.com/2024/a.avif"
}

Troubleshooting

Development

uv sync
uv run pytest
uv run pix --version
uv build

The code must stay compatible with Python 3.11. See development.md for tests, packaging and release details. Behavior is specified in architecture.md; rationale lives in decisions.md.

The detailed docs are currently written in Chinese.