Skip to content

feat: add configurable image subfolder strategies#8969

Open
Pfannkuchensack wants to merge 7 commits intoinvoke-ai:mainfrom
Pfannkuchensack:feat/image-folder-options
Open

feat: add configurable image subfolder strategies#8969
Pfannkuchensack wants to merge 7 commits intoinvoke-ai:mainfrom
Pfannkuchensack:feat/image-folder-options

Conversation

@Pfannkuchensack
Copy link
Collaborator

Summary

Add support for organizing output images into subfolders instead of a single flat directory. Four strategies are available via the image_subfolder_strategy config setting:

  • flat (default): Current behavior, all images in one directory
  • date: Organized by YYYY/MM/DD
  • type: Organized by image category (general, intermediate, mask, etc.)
  • hash: UUID prefix for filesystem performance (~256 evenly distributed subfolders)

The strategy can be changed at any time — existing images keep their paths, only new images use the new strategy. This is achieved by storing each image's subfolder in a new image_subfolder DB column.

  • image_name (DB primary key) remains unchanged — no API or frontend changes needed
  • A separate image_subfolder column stores the relative path prefix
  • Old images get image_subfolder = "" (backward compatible, stays in root)
  • Path traversal protection is maintained while allowing controlled subdirectories
  • Thumbnails mirror the same subfolder structure

QA Instructions

  1. Start InvokeAI with default config (image_subfolder_strategy: flat) — verify images are saved to outputs/images/ as before
  2. Set image_subfolder_strategy: date in invokeai.yaml, restart, generate an image — verify it appears in outputs/images/YYYY/MM/DD/
  3. Set image_subfolder_strategy: type, generate — verify images land in outputs/images/general/ (or intermediate/ for intermediate images)
  4. Set image_subfolder_strategy: hash, generate — verify images land in outputs/images/XX/ (first 2 chars of UUID)
  5. Switch back to flat — verify old subfolder images are still accessible in the gallery
  6. Test "Clear Intermediates" — verify it works across all strategies
  7. Test image download/bulk download with mixed subfolder images

Merge Plan

  • DB migration 28 adds a new column with a default value — safe to run on existing databases
  • Config schema migrates from 4.0.2 to 4.0.3 automatically
  • No frontend changes required
  • No breaking API changes

Checklist

  • The PR has a short but descriptive title, suitable for a changelog
  • Tests added / updated (if applicable)
  • ❗Changes to a redux slice have a corresponding migration
  • Documentation added / updated (if applicable)
  • Updated What's New copy (if doing a release after this PR)

Add support for organizing output images into subfolders instead of a
single flat directory. Four strategies are available via the
image_subfolder_strategy config setting: flat (default, current
behavior), date (YYYY/MM/DD), type (by image category), and hash (UUID
prefix for filesystem performance). The strategy can be changed at any
time - existing images keep their paths, only new images use the new
strategy.
@github-actions github-actions bot added api python PRs that change python files services PRs that change app services docs PRs that change docs labels Mar 17, 2026
@github-actions github-actions bot added the frontend PRs that change frontend files label Mar 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

api docs PRs that change docs frontend PRs that change frontend files python PRs that change python files services PRs that change app services

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant