Reference Image

ReferenceImage is the current, supported image loader in this pack - the one to add from the menu. It does one small job well: take a full path to an image anywhere on your disk and give you an IMAGE (plus a MASK) without the file ever entering ComfyUI/input. If your workflow has a LibraryImage, that's this same node under its pre-0.1.2 id.

But it's worth being clear about its role, because people install this pack expecting the loaders to be the point and they aren't. The star of the show is the Reference Prompt: named libraries of files, @name in your prompt, and the files get wired into a model's image inputs at queue time with no wires drawn. These loader nodes are the optional hand-wiring path - "optional, for wiring files by hand", as the README puts it. You reach for ReferenceImage when you want to do something deliberate with one specific file: preview it, resize it, upscale it, pull its alpha, feed an IP-Adapter, or send it somewhere the Reference Prompt doesn't manage.

What it does with the file

The load is more careful than the node's size suggests. It opens with Pillow inside a with block (so Windows doesn't keep a file handle open and lock the file), applies EXIF rotation, converts to RGB, and normalises to a float tensor. Multi-frame files - animated PNG, GIF, WebP, MPO - come back as every frame stacked into one batch, with frames whose size differs from the first one skipped rather than blowing up the run.

The mask output is the file's alpha channel, inverted to ComfyUI's convention where white means "keep". No alpha channel? You get an all-zero mask at the image's dimensions rather than a None you have to guard against. That's a genuinely nice design decision: alpha-bearing reference PNGs go straight into inpainting or compositing graphs without a separate detour through Load Image.

It also gets caching right: IS_CHANGED hashes path + mtime + size. Re-render Alex.png and the node re-runs; leave it alone and the graph behind it stays cached. If you've ever been bitten by a fancy loader that only ever returns NaN to force reruns and killed your cache, this is the opposite of that.

Inputs and outputs

• image_path - "Full path to an image file anywhere on disk." Absolute; the Browse… button opens a native dialog and fills it in for you.
• name - "Tag used as @name in the prompt. Empty = file name without extension." Picking a file with Browse… fills this with the file stem and retitles the node @stem unless you've set your own name. This is the field that makes the node part of the pack: @Alex in a Reference Prompt refers to this exact file, and renaming the asset later keeps the tag pointing at it.
• image (IMAGE) and mask (MASK) out. The image goes to a model input, an upscaler, a ControlNet preprocessor, a Reference Prompt's image_1; the mask goes wherever a mask goes.

Install

cd ComfyUI/custom_nodes
git clone https://github.com/PixelMonkey77/comfyui-reference-library

Restart ComfyUI - or install the same URL through ComfyUI Manager (Install via Git URL). No requirements.txt, no model downloads; the pack's dependency list is deliberately empty and it uses only what ships with ComfyUI.

You need Settings → Comfy → Nodes 2.0 → Modern Node Design (Nodes 2.0). The pack is written against ComfyUI's newer frontend, and the classic canvas is unsupported. In 2026 that's a real trade - Nodes 2.0 is the rewrite that broke rendering in a bunch of established packs, and some people run the legacy canvas for that reason. If that's you, skip this pack rather than fighting it.

Where people get stuck

Relative paths are rejected. A bare portrait.png gets an error with the message "Use a full path (for example D:\Pictures\cat.png), not one relative to ComfyUI's folder." Windows' "Copy as path" quotes are stripped automatically, ~ expands, but %VAR% and $VAR do not - a queued path shouldn't be able to read environment variables back through an error message.

A new folder shows a yellow note on the node. By design. The loaders only read from folders the pack has used: ones where you picked a file in Browse… or + Add, folders holding library files, and ComfyUI's input/output. Pick the file once with Browse… and that folder is trusted from then on. The reason is that this pack can send your references to a paid API - a shared workflow should not be able to name any file on your disk and have it leave the machine.

Library editing refuses to work. Picking files and changing libraries only works when ComfyUI is open at http://127.0.0.1 or http://localhost. On a --listen setup another machine can read file names but can't browse your folders.

Confusing it with LibraryImage. Same node. Add the current id for new work; leave the old one alone in workflows that already have it.