Stash Performer Image Loader (Fuzzy Match)

Plugins Other Projects
,
1
:placard: Summary Assign local images to Stash custom performers using fuzzy name matching.
:link: Repository https://github.com/iGoMango/stash-performer-image-loader/blob/main/scripts/find_custom_performers_pfp.py

Hey everyone,

I’ve been working on a small utility script to make it a lot easier to bulk assign performer avatars, especially for custom performers that aren’t in StashDB (like TikTok usernames or other non-database performers).

Instead of clicking through one-by-one, this script will:

  • Scan a folder of local images (JPG/PNG/WebP)
  • Fuzzy-match filenames to performers already in your Stash library
  • Upload them as performer avatars via the GraphQL API

Repo

:open_file_folder: GitHub – iGoMango/stash-performer-image-loader

Requirements

Install dependencies:

pip install -r requirements.txt

Usage

  1. Clone the repo:

    git clone https://github.com/iGoMango/stash-performer-image-loader.git
cd stash-performer-image-loader/scripts

  2. Copy .env.example → .env and set:

    • STASH_URL=http://localhost:9999/graphql
    • API_KEY=your_api_key
    • IMG_DIR=/absolute/path/to/your/images

  3. Run:

    python3 find_custom_performers_pfp.py

The script will show which performer was matched for each image. If you want to preview results without uploading, set DRY_RUN=true in .env.

Example

If you have images like:

john..doe_0_0f58575a_avatar.jpeg
joeshmoe._0_7fa78f20_avatar.jpeg

The script will normalize them and assign them to performers named john..doe or joe shmoe in your Stash library (if present).

Notes

  • Fuzzy threshold defaults to 75 (adjustable).
  • Matches are logged so you can review before committing.
  • Great for bulk-adding avatars for performers you’ve manually created.

May create a plugin at some point.

2

Moved to more appropriate category.