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
• At least one remote already configured in rclone

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

Install

Not yet published on PyPI; install from source:

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

Linux installs ~/.local/bin/pix; Windows installs %USERPROFILE%\.local\bin\pix.exe. An editable install picks up source changes immediately. Reinstall with uv tool install --force --editable ., or remove it with uv tool uninstall pix-cli.

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.

Common keys:

Precedence is command line > pix config > built-in defaults. --exclude is appended to config excludes rather than replacing them. -q means quality; silence is --quiet (no short form).

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. Changing width, quality or effort triggers a full re-encode. --dry-run only prints the plan.

3. Mirror originals:

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

   --resync is required on the first run. Always preview with --dry-run first.

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 and always excludes .pix/**. The URL manifest is printed to stdout as JSON only after a successful, non-dry-run sync.

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 --urls
   

   Only changes are encoded and transferred.

Command cheat sheet

Safety rules

Output and exit codes

• Logs and progress go to stderr.
• stdout carries doctor reports, --dry-run plans and --urls JSON.
• Exit codes: 0 success, 1 runtime failure, 2 argument or configuration error.
• mirror / publish return rclone's exit code unchanged.

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.