PixlStash

PixlStash is a local picture library server for organizing, filtering, and reviewing large image collections.

It provides:

• A desktop application or a headless server with a browser-based interface
• Automatic tagging and image descriptions with selectable AI engines (including JoyCaption)
• Re-tag or regenerate descriptions for any selection directly from the context menu
• Instant grid loading — thumbnails appear immediately, metadata fills in asynchronously
• Fast metadata and tag filtering
• Smart score sorting
• Character and set organization
• Local storage of your library data
• API for integrating with other tools
• Simple keyboard shortcuts for scoring, selection, tagging, deletion and navigation.
• Integration with ComfyUI for running workflows on selected images within PixlStash.
• Plugin system for defining new filter operations that can be performed on a set of images.
• Sharing of pictures, picture sets, characters and projects.
• Persistent view URLs — bookmark or refresh any view and land exactly where you left off.
• Undo and Redo with keyboard shortcuts and history
• Deduplication helper
• Tag review helper
• A model overview for keeping track of your generative AI models
• Swappable image library
• Scriptable backup

PixlStash runs on your machine and serves the UI at a local (or Internet-facing) web address.

How is this different from Immich?

Immich is a very good home photo server. If that's what you need, use it! PixlStash does a different job.

PixlStash is a tool for working with images rather than just storing them, though it works as a home server too. It adds a tag review queue so auto-tags are verified, segmentation and selectable taggers, a choice of GPU or CPU backends, and two-way ComfyUI integration: control ComfyUI from PixlStash, or call its nodes from your own workflows. Generated images return tagged, with People, Picture Set, and Project associations attached.

Install or try PixlStash

PixlStash is available as a native desktop app for Windows, macOS (Apple Silicon), and Linux (no Python or browser tab required), as a Docker image, or as a pip package that runs anywhere Python does (including Intel Macs). The desktop app ships a ready-to-run CPU runtime, so it works offline out of the box, and auto-detects your hardware to offer optional GPU acceleration (NVIDIA CUDA, or experimental AMD ROCm), which it installs on demand straight from PyPI / PyTorch.

Detailed installation instructions on pixlstash.dev.

First run and data location

On first run, PixlStash creates a user config directory and stores:

• Server config
• Database
• Imported media files

The desktop app uses this same platform user data directory, so a desktop install shares its library with a pip or Docker install on the same machine. If you add GPU acceleration, the desktop app stores the downloaded GPU wheels under the app's own user-data directory.

Model downloads: On first startup, PixlStash automatically downloads the AI models required for tagging, captioning, and quality scoring. This includes several hundred MB of model weights. Downloads are stored in the platform user data directory:

OS	Path
Linux	~/.local/share/pixlstash/downloaded_models/
macOS	~/Library/Application Support/pixlstash/downloaded_models/
Windows	%LOCALAPPDATA%\pixlstash\downloaded_models\

An internet connection is required the first time the server starts. Subsequent starts use the cached models.

Moving them somewhere else: open Model folders on the model shelf and use Move on PixlStash's own folder. Every file in it is copied, verified and removed from the old location, and the new location is remembered — so nothing is downloaded again. Set PIXLSTASH_BUILTIN_MODEL_DIR instead if you want the folder somewhere else without moving what is already in it (a mounted model volume, typically).

If you need to use a custom config path:

python -m pixlstash.app --server-config "C:\path\to\server-config.json"

Multiple libraries

PixlStash can register several independent image libraries and keep one open at a time. Pictures, tags, scores, snapshots, guest sessions, and guest scores stay with their library; your owner account and preferences stay with the installation. Switch from Settings → Libraries. API tokens and share links are pinned to the library where they were created: they become inactive while a different library is open and work again when you switch back.

The library command line

Adding and removing libraries is a command-line operation in this release, because it points PixlStash at folders on your machine. Settings → Libraries shows the exact command for your installation, with a copy button.

Run these on the machine hosting PixlStash, as the OS user that owns hub.db, with the same environment active that the server runs in (activate the venv, or use the same interpreter). That is the one assumption the short form makes; if the commands are not found, see Which form to type below.

pixlstash-cli libraries list
pixlstash-cli libraries create /path/to/new-library --name "New library"
pixlstash-cli libraries attach /path/to/existing-library --name "Existing library"
pixlstash-cli libraries rename "Existing library" "Better name"
pixlstash-cli libraries relocate "Existing library" /new/path
pixlstash-cli libraries detach "Existing library"
pixlstash-cli libraries backup "Existing library" /path/to/backups/
pixlstash-cli libraries backup "Existing library" /path/to/backups/monday.tar.zst
pixlstash-cli libraries restore /path/to/backups/monday.tar.zst /path/to/new-library

Notes worth knowing before you need them:

• detach refuses the active library. Switch to another one first.
• Reattaching the same folder revives its original registration, including its share links, because a library carries a fingerprint of its own identity.
• A backup is a zstd-compressed tar, named .tar.zst — not .tar.gz. --no-compress writes a plain .tar instead. Given a folder, backup invents a dated name with the right ending; given a filename, it adds the right ending if you left it off. restore recognises an archive by its contents, so a renamed file still works.
• A backup contains hub.db, and therefore your login and token secrets. PixlStash writes it owner-readable and refuses to overwrite an existing file.
• A backup covers the library folder. Pictures kept in reference folders live outside it and are not included, so back those up separately.
• Backing up finishes any outstanding one-time snapshot cleanup first, so the archive never carries credentials from before your upgrade.
• restore needs PixlStash stopped, and names a folder that is empty or does not exist yet — it never writes over a library. Because the archive holds the hub, restoring also brings back the password and API tokens that library was using, so your current ones are replaced.
• restore does not delete your current setup. It moves server-config.json and hub.db into a dated pre-restore-* folder beside themselves and prints the launch command for each, so pixlstash-server --server-config <pre-restore-*>/server-config.json reopens what you had. Your old library folder is never touched.

Which form to type

The commands above assume pixlstash-cli is on your PATH, which is true once the environment PixlStash is installed into is active.

• Source checkout, or an environment you have not activated: python -m pixlstash.cli libraries list
• Docker Compose, for a running service (paths are inside the container): docker compose exec pixlstash pixlstash-cli libraries list
• Desktop app (AppImage, deb, .dmg, installer): the app is its own CLI, so /path/to/PixlStash.AppImage cli libraries list works whether or not the app is running. Turn on Settings › Backend › Desktop › Shell command to get a pixlstash command in ~/.local/bin and type pixlstash libraries list instead. Either form targets the desktop app's own hub; there is no need to pass --hub. Settings › Libraries always shows the exact command for your install.
• A different hub than the default: put global options before libraries, e.g. pixlstash-cli --hub /path/to/hub.db libraries list. Without --hub the CLI uses the standard config location, which is what you want almost always.

Required one-shot preparation when upgrading

If an older installation already has its owner and tokens inside vault.db, normal startup deliberately will not guess from the config file or from finding an existing vault; it needs that exact legacy vault authorized once.

• Desktop app: setup performs this step only after you explicitly approve importing the detected legacy owner and tokens.
• pixlstash-server / python -m pixlstash.app, in an interactive terminal: startup detects the unprepared legacy vault itself and asks, with a plain explanation and a [y/N] prompt — defaulting to no, since this is irreversible — before doing anything. Saying yes does the same thing the CLI command below does, in the same startup, so no separate step or restart is needed. After this runs, the vault is no longer readable as an owner/token store by versions of PixlStash older than the hub — the prompt says so before you answer.
• Non-interactive launches (a service, a container, redirected stdin) log that the legacy vault needs preparing instead of asking, and the CLI command below remains the way to authorize the migration ahead of time.

Pip installation:

pixlstash-cli --hub /path/to/config-dir/hub.db libraries prepare-legacy-identity /path/to/library

Source checkout:

python -m pixlstash.cli --hub /path/to/config-dir/hub.db libraries prepare-legacy-identity /path/to/library

Docker Compose, before bringing the upgraded service up (adjust the two container paths if you configured custom mounts):

docker compose run --rm --entrypoint pixlstash-cli pixlstash \
  --hub /home/pixlstash/.config/pixlstash/hub.db \
  libraries prepare-legacy-identity \
  /home/pixlstash/.config/pixlstash/images

After the command succeeds, start PixlStash normally. Startup verifies the approved path and identity digest, copies the owner/tokens into the hub, stamps the library, and only then removes portable owner, token, and guest-session data from the live vault and its historical snapshots. New snapshots and every restore scratch database receive the same sanitation, so identity remains hub-only. If verification fails, the hub does not mark the migration complete; correct the reported problem and retry.

Server configuration

On first run, PixlStash generates a server-config.json file in the user config directory:

• Linux / macOS: ~/.config/pixlstash/server-config.json
• Windows: %LOCALAPPDATA%\pixlstash\server-config.json

You can also supply a custom path with --server-config <path>.

On first run in an interactive terminal, PixlStash now launches a short setup wizard for:

• image_root (storage path)
• port
• require_ssl (HTTP/HTTPS)

Before the server starts, bootstrap also offers to set (or replace) the initial username/password.

You can rerun the wizard at any time with:

python -m pixlstash.app --bootstrap

When rerunning the wizard, pressing Enter keeps existing values as defaults.

Edit the file and restart the server to apply changes.

Network and port

At startup the server detects its own LAN IP and automatically allows it on any port. This means the Vite dev server works over LAN (http://<lan-ip>:5173 → http://<lan-ip>:9537) without any extra configuration, as long as network access is enabled via host.

Use cors_origins only if you need to allow origins on a different machine entirely.

Sharing and remote access

PixlStash supports read-only share tokens that let you give guests access to a specific picture, picture set, character, or project without exposing your full account. To safely share over the internet while keeping your login protected:

1. Expose the server — set "host": "0.0.0.0" and open/forward the port.
2. Enable HTTPS — set "require_ssl": true (strongly recommended whenever the server is internet-facing; see SSL / HTTPS below).
3. Keep require_local_for_write: true (the default) — this ensures that full login is only possible from your local network or VPN. Share tokens (READ-only) continue to work from any IP.
4. Create a share token — in the PixlStash settings UI, create a READ-only token scoped to the resource you want to share. Copy the generated URL and send it to your guests.

If you run a reverse proxy (nginx, Caddy, Cloudflare Tunnel…)

When a proxy sits in front of PixlStash, require_local_for_write sees the proxy's IP instead of the real client IP. You must tell PixlStash which proxy addresses to trust so it reads the real IP from the X-Forwarded-For header:

Example:

{
  "host": "0.0.0.0",
  "require_ssl": true,
  "require_local_for_write": true,
  "trusted_proxies": ["127.0.0.1"]
}

Warning: Only add addresses you control to trusted_proxies. Trusting an untrusted address allows that host to spoof any client IP, bypassing the local network restriction entirely.

SSL / HTTPS

When require_ssl is enabled and no certificate files exist at the configured paths, PixlStash generates a self-signed certificate automatically. Browsers will show a security warning for self-signed certs. To get a trusted certificate without warnings, choose one of the options below.

Option A — Replace the auto-generated certificate with a real one

If you already have a certificate (e.g. from certbot or your DNS provider), drop the files into the config directory and restart:

Place your private key as key.pem and the full certificate chain as cert.pem, or point ssl_keyfile / ssl_certfile at any paths you prefer.

To obtain a cert with certbot (requires port 80 reachable and a real domain):

certbot certonly --standalone -d pixlstash.example.com --email you@example.com

Then in server-config.json:

{
  "require_ssl": true,
  "cookie_secure": true,
  "ssl_keyfile": "/etc/letsencrypt/live/pixlstash.example.com/privkey.pem",
  "ssl_certfile": "/etc/letsencrypt/live/pixlstash.example.com/fullchain.pem"
}

Certbot installs a systemd timer / cron job that renews automatically. The --standalone renewal briefly needs port 80; use a pre/post hook to stop and restart PixlStash around the renewal if it is bound to port 80.

Option B — Caddy as a reverse proxy (automatic Let's Encrypt)

Caddy provisions and renews a trusted TLS certificate automatically whenever it proxies a request for a real domain. No manual cert management required.

1. Install Caddy: sudo apt install caddy (or see caddyserver.com)
2. Create /etc/caddy/Caddyfile:

   pixlstash.example.com {
       reverse_proxy localhost:9537
   }
   

3. sudo systemctl reload caddy

PixlStash itself can stay on plain HTTP (require_ssl: false); Caddy terminates TLS externally. Set "trusted_proxies": ["127.0.0.1"] in server-config.json so that require_local_for_write correctly identifies the real client IP (see Sharing and remote access).

Option C — Cloudflare Tunnel (no open port, no domain purchase required)

Cloudflare Tunnel routes traffic to PixlStash through Cloudflare's edge without opening any inbound firewall ports. Cloudflare provides a free *.trycloudflare.com subdomain with a valid TLS certificate, or you can use your own domain.

# Install cloudflared, then:
cloudflared tunnel --url http://localhost:9537

Cloudflare terminates TLS; PixlStash runs plain HTTP internally. As with Caddy, set "trusted_proxies": ["127.0.0.1"] so local-write restrictions work correctly.

Storage

Automatic import folders are stored in the database and managed via the Import Folders UI/API, not in server-config.json.

Processing

Face model pack and licensing

insightface_model_pack selects which InsightFace model pack powers face detection and face recognition. The licensing decision is yours; PixlStash simply makes the choice available.

• buffalo_l (default): the standard InsightFace pack. Its recognition weights are trained on the WebFace600K dataset, which is licensed for non-commercial research use only. This is the right choice for personal and research use, and it downloads automatically on first use.
• auraface: the fal/AuraFace-v1 pack, whose weights are Apache-2.0 licensed and therefore suitable if you need to use face features in a commercial setting. It uses the same SCRFD-10G face detector as buffalo_l, so switching only changes the recognition embedding. When selected, PixlStash downloads the pack from a pinned HuggingFace revision into ~/.insightface/models/auraface/ on first use. If the automatic download fails (for example, no network access), you can place the pack's .onnx files in that directory manually and restart.

Changing this setting on an existing library does not delete your faces or your manual character assignments. PixlStash detects faces whose embeddings came from a different pack and refreshes those embeddings in place, in the background, keeping each face's identity intact. New imports are always processed first, so a refresh sweep never starves brand-new pictures.

To remove stale database records for missing source files at startup, run:

python -m pixlstash.app --cleanup-missing-pictures

Logging

Example config

{
  "host": "localhost",
  "port": 9537,
  "log_level": "info",
  "require_ssl": false,
  "image_root": "/home/user/.config/pixlstash/images",
  "default_device": "cpu",
  "insightface_model_pack": "buffalo_l",
  "generate_thumbnails_on_startup": true
}

Upgrade PixlStash

Detailed installation instructions on pixlstash.dev.

Installing plugins

PixlStash supports built-in plugins and user-created plugins.

With the CLI (recommended)

pixlstash-cli plugins available                     # what is published
pixlstash-cli plugins available caption             # ...matching a word
pixlstash-cli plugins install hello_world_stamp     # from the plugins repository
pixlstash-cli plugins install ./my_captioner.zip    # a zip of a plugin folder
pixlstash-cli plugins install ./my_captioner/       # an extracted folder
pixlstash-cli plugins install ./my_filter.py        # a single module
pixlstash-cli plugins test ./my_captioner.py       # does it load and render?
pixlstash-cli plugins list
pixlstash-cli plugins remove my_captioner

plugins available lists what PixlStash-plugins publishes, with each plugin's name, title, one-line summary and (where declared) author and licence; * marks one you already have. Add a word to search, and it matches any of those fields, so anything you can see in the listing you can search for. It downloads the same archive install does and reads it without importing anything, so it needs no token and runs no published code.

The destination differs by kind (captioning plugin or image filter) and by shape, so install works it out from the source instead of asking you to type it: it reads the source without importing it, decides which base class it derives from, and names the installed file after the plugin's own name. It refuses a source that is not a plugin, one whose name collides with a built-in, and a zip whose entries would be unpacked outside the folder it is unpacked into.

--dry-run prints the plan and stops, --yes skips the confirmation, --force replaces an existing plugin of the same name, and --strict turns the warnings into refusals. --ref picks a branch, tag or commit in the plugins repository and is ignored for local sources; it cannot point the download at a different repository. A plugin's requirements.txt is never installed unless you pass --with-deps. Plugin code runs unsandboxed, in the server process, with your permissions — install what you would run yourself.

Captioning plugins load at server start, so restart PixlStash after installing one; image filters are re-scanned every time the Filters menu is listed.

plugins test is for the person writing a captioning plugin, and it is the one verb that imports the plugin instead of reading it: it loads the file the way the server does, registers what it defines, and checks that the parameter schema is one the settings screen can render — so a typo costs a command rather than a restart. --image PATH runs it over one picture as well, and stops instead of running when the plugin reports its model is not present — though a plugin that downloads inside init() still will, since by then it is the plugin's code deciding.

It is a development aid, not a security scanner. It does not tell you whether a plugin is safe to install — it runs the plugin, unsandboxed, with your permissions, which is exactly what the server would do. Only test a plugin you would have installed anyway.

User plugin directory

If you prefer to copy files by hand, they go in the platform-specific user data directory. PixlStash logs the exact path on startup, and pixlstash-cli plugins list prints it.

The doubled pixlstash\pixlstash on Windows is not a typo: platformdirs puts the app under a vendor folder, and PixlStash passes no separate vendor name. This table used to show it singly, which is why copying a plugin there by hand appeared to do nothing.

An image filter is always a single .py file. A captioning plugin may be a single .py file or a folder containing __init__.py.

Writing a plugin

Use the template from pixlstash/image_plugins/built-in/plugin_template.py in the source repository as a starting point:

1. Create a new .py file in your user plugin directory.
2. Subclass ImagePlugin, set a unique name and plugin_id, and implement run().
3. Restart PixlStash Server — plugins are loaded at startup.

plugin_template.py is ignored by plugin discovery and will not be loaded as a plugin.

Plugin licensing

PixlStash backend core is GPL-3.0, but the plugin authoring API files pixlstash/image_plugins/base.py and pixlstash/image_plugins/built-in/plugin_template.py are MIT-licensed.

This means user plugins that only rely on that plugin API/template may use any license chosen by the plugin author.

If a plugin copies substantial GPL backend code or depends directly on other GPL-only backend internals, different obligations may apply.

Troubleshooting

• If the page does not load, confirm the server process is running.
• If port 9537 is in use, set a different port in your server config file.
• If frontend assets are missing, rebuild frontend with npm run build and restart the server.
• Mobile browsers: the UI is designed for desktop. Mobile may work for basic browsing but is not a supported layout in 1.0.0.

Docker Images

PixlStash maintains separate Dockerfiles:

• Dockerfile: CPU image
• Dockerfile.gpu: GPU image (NVIDIA CUDA)

Build locally:

# CPU
docker build -f Dockerfile -t pixlstash:cpu .

# GPU
docker build -f Dockerfile.gpu -t pixlstash:gpu .

Run locally:

# CPU
docker run --rm -p 9537:9537 -v pixlstash_data:/home/pixlstash pixlstash:cpu

# GPU
docker run --rm --gpus all -p 9537:9537 -v pixlstash_data:/home/pixlstash pixlstash:gpu

First-run setup in Docker

Claiming the owner account (choosing the first username/password) is normally restricted to loopback connections, and a Docker container never sees your traffic as loopback — so the in-browser first-run setup is blocked with a 403. Provision the owner account via environment variables on the first run instead:

docker run --rm -p 9537:9537 \
  -e PIXLSTASH_INITIAL_USERNAME=owner \
  -e PIXLSTASH_INITIAL_PASSWORD=change-me-now \
  -v pixlstash_data:/home/pixlstash pixlstash:cpu

The account is claimed at startup and you can log in with those credentials right away. Afterwards, restart the container without the two variables: they are only used to claim a still-unclaimed account (a restart with stale values never changes an existing password — it just logs that they were ignored), but credentials should not linger in the container environment. docker-compose.yml ships the same two variables commented out.

Alternative: log in over loopback from inside the container, e.g. docker exec -it <container> curl -X POST http://127.0.0.1:9537/api/v1/login -H 'Content-Type: application/json' -d '{"username":"owner","password":"change-me-now"}'.

GitHub Actions uses the same split in .github/workflows/docker-publish.yml:

• CPU publish job builds from Dockerfile
• GPU publish job builds from Dockerfile.gpu

GPU startup fails (CUDAExecutionProvider unavailable)

If startup reports that ONNX CUDAExecutionProvider is unavailable, you likely have CPU-only ONNX Runtime installed.

Fix your environment:

pip uninstall -y onnxruntime
pip install onnxruntime-gpu

It some cases you may have to uninstall onnxruntime-gpu and reinstall it.

Verify providers:

python -c "import onnxruntime as ort; print(ort.get_available_providers())"

Expected output should include CUDAExecutionProvider.

If you prefer CPU mode, set "default_device": "cpu" in server-config.json.

Import Folders and Reference Folders in Docker

Because Docker containers have an isolated filesystem, folders on your host machine must be explicitly bind-mounted into the container before PixlStash can read them.

Key restrictions:

• No folder browser. The path browser is unavailable in Docker. You must type the host path manually in the folder editor.
• Volume mount required before the folder becomes active. When you add a new Import or Reference folder, PixlStash saves it with a pending_mount status. The folder will not scan or import until you restart the container with the corresponding -v mount in your docker run command.
• Container restart needed for each new folder. Adding a folder in the UI does not automatically mount it. You must stop and recreate the container with the new -v flag, then open PixlStash again.

Workflow:

1. Open the sidebar Folders tab and add a new Import or Reference folder.
2. Enter the host path (the path on your machine) and note the suggested container path (e.g. /data/import/pictures-001 or /data/ref/pictures-001).
3. The editor shows a ready-to-copy docker run restart command that includes all current mounts. Copy and run it to recreate the container with the new mount.
4. After the container restarts, the folder status changes from pending_mount to active and scanning begins.

Example — adding a reference folder to an existing GPU container:

docker rm -f pixlstash-gpu 2>/dev/null || true
docker run -d \
  --runtime nvidia \
  -e HOME=/home/pixlstash \
  -e PIXLSTASH_HOST=0.0.0.0 \
  -p 9537:9537 \
  -v ~/Pictures/pixlstash:/home/pixlstash \
  -v '/home/you/Photos:/data/ref/pictures-001' \
  --name pixlstash-gpu \
  ghcr.io/pikselkroken/pixlstash:latest-gpu

Replace /home/you/Photos with your actual host path and adjust the container path index if you have multiple folders.