Extensions/ComfyUI-RWImageS3
ComfyUI Extension

ComfyUI-RWImageS3

A powerful ComfyUI extension that enables seamless integration with AWS S3 storage for reading and saving images directly within your ComfyUI workflows. This extension eliminates the need for manual file transfers by providing direct S3 connectivity for your image processing pipelines.

By lakkiy·Created about a year ago·Updated 17 days ago· 1
lakkiy/ComfyUI-RWImageS3
Nodes5
On cloudLocal install
Categorysd, image
Stars1
Updated17 days ago
Readme

ComfyUI-RWImageS3

ComfyUI custom nodes for reading images from S3 and saving images/videos to S3.

Features

  • Read an image directly from S3 using an explicit s3_key
  • Support HEIC/HEIF uploads when pillow-heif is installed, even if the S3 key is mislabeled as .png/.jpg
  • Automatically fall back to the first frame when the downloaded object is actually a video/live photo
  • Save an IMAGE batch to S3 using an explicit s3_key, with a native ComfyUI preview in the node
  • Save a video to S3 from a native ComfyUI VIDEO, VideoHelperSuite's Video Combine, or a local file path, with a video preview in the node
  • Read a video from S3 as a local file path (for VideoHelperSuite's Load Video (Path)) and a native ComfyUI VIDEO
  • Multiple named S3 key sets: pick one per node in ComfyUI, or let reads try them all in order
  • Optional custom S3 endpoint support (R2, MinIO, etc.)
  • Upload/download timing logs in ComfyUI console

Installation

  1. Clone into ComfyUI custom nodes:
cd /ComfyUI/custom_nodes
git clone https://github.com/lakkiy/ComfyUI-RWImageS3.git
cd ComfyUI-RWImageS3
  1. Install dependencies:
pip install -r requirements.txt

requirements.txt now includes pillow-heif, so Read Image From S3 can support HEIC/HEIF uploads whose S3 key may still look like .png/.jpg.

  1. Ensure ffmpeg is available in PATH if you want Read Image From S3 to support:

    • files whose extension says .png/.jpg but whose actual contents are video
    • Apple Live Photo companion videos (.mov)
    • other video inputs where only the first frame should be used
  2. Edit .env (it ships as a template). One key set is enough:

S3_NAME=aws
S3_ACCESS_KEY_ID=your_access_key
S3_SECRET_ACCESS_KEY=your_secret_key
S3_REGION=us-east-1
S3_BUCKET=your-bucket
# S3_ENDPOINT_URL=https://your-endpoint   # optional, for R2 / MinIO / ...

For more key sets, add numbered ones starting at 2:

S3_2_NAME=r2
S3_2_ACCESS_KEY_ID=...
S3_2_SECRET_ACCESS_KEY=...
S3_2_BUCKET=your-r2-bucket
S3_2_ENDPOINT_URL=https://your-account.r2.cloudflarestorage.com

# S3_3_*, S3_4_*, ... add as many as you need
  • BUCKET is required; a set without it is ignored. REGION (default us-east-1) and ENDPOINT_URL are optional.
  • NAME is what shows up in the node's s3_source dropdown (default default for the first set, s3_<N> for the others). Names must be unique; duplicates get a (2) suffix.
  • auto tries the first set, then S3_2, S3_3, ... Gaps are fine (S3_2, S3_4).

Old-style variables still work, so existing .env files need no change. They are loaded before the numbered sets:

| Old variables | Name in dropdown | | --- | --- | | AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, S3_BUCKET_NAME, ENDPOINT_URL | primary | | FALLBACK_AWS_ACCESS_KEY_ID, ..., FALLBACK_S3_BUCKET_NAME, FALLBACK_ENDPOINT_URL | fallback 1 | | FALLBACK_2_*, FALLBACK_3_*, ... | fallback 2, fallback 3, ... |

  1. Restart ComfyUI.

Nodes

Read Image From S3

Category: image

Input:

  • s3_key (STRING): Full object key in bucket, e.g. images/cat.png
  • s3_source (optional dropdown): auto (try in order) (default) or one key set name

Output:

  • IMAGE

Behavior:

  • auto: tries each key set in order until one succeeds (same as the old primary → fallback behavior)
  • A named key set: downloads only from that one, nothing else is tried
  • First tries image decoding with Pillow
  • If pillow-heif is installed, this also covers HEIC/HEIF files
  • If the image is animated, it uses the first frame
  • If Pillow cannot decode the file, it automatically uses ffmpeg to extract the first frame
  • This means it can handle:
    • normal images
    • animated images
    • HEIC/HEIF uploads
    • files mislabeled as .png/.jpg in S3 but actually containing video
    • Apple Live Photo video files such as .mov
  • Converts output to RGB tensor in [0, 1]

Save Image To S3

Category: image

Input:

  • image (IMAGE)
  • s3_key (STRING): Full target object key, e.g. results/run1/frame.png
  • s3_source (optional dropdown): which key set to upload with (default: the first one)

Output:

  • No outputs (OUTPUT_NODE = True), so it can be the last node of a workflow

Behavior:

  • Converts each image to PNG and uploads it to S3
  • Sets the object's Content-Type from the s3_key extension (e.g. image/png), so a bucket served straight to browsers shows it
  • 1 image: uploaded to s3_key as-is
  • A batch of N images: a number is added before the extension, e.g. results/run1/frame_00001.png, frame_00002.png, ...
  • Shows the images in the node using ComfyUI's own Preview Image (temp files, same as the Preview Image node). If the preview fails, the upload still succeeds.
  • Prints upload completion log with duration

Save Video To S3

Category: image

Input (connect exactly one of video, filenames, video_path):

  • s3_key (STRING): Full target object key, e.g. results/run1/clip.mp4
  • video (VIDEO, optional): native ComfyUI video, e.g. from Create Video or Load Video. Written as mp4, mkv or webm based on the s3_key extension (anything else is written as mp4).
  • filenames (VHS_FILENAMES, optional): the Filenames output of VideoHelperSuite's Video Combine. The final video file (the one with audio, if any) is uploaded.
  • video_path (STRING, optional, force input): Absolute local path, e.g. /root/autodl-tmp/ComfyUI/output/clip.mp4
  • s3_source (optional dropdown): which key set to upload with (default: the first one)
  • faststart (BOOLEAN, optional, default on): for .mp4 / .mov / .m4v, move the moov atom to the front before uploading

Output:

  • No outputs (OUTPUT_NODE = True), so it can be the last node of a workflow

Behavior:

  • With faststart on, remuxes mp4/mov with ffmpeg -c copy -movflags +faststart into a temp file and uploads that: no re-encode, metadata kept, takes well under a second for a few MB. Video Combine (VHS) has no faststart option, so its mp4s otherwise keep the moov at the end and browsers must fetch the tail before playing. Uses ffmpeg from PATH, else imageio-ffmpeg's; if neither is found or the remux fails, it logs a warning and uploads the original. The preview shows the original file.
  • For filenames / video_path: validates absolute path, file existence and extension (.mp4 .mov .webm .mkv .avi .gif .webp)
  • Uploads the file to S3 and prints upload duration
  • Sets the object's Content-Type from the s3_key extension (e.g. video/mp4); an unknown extension leaves it to the storage default
  • Shows the video in the node, in the same format as ComfyUI's Save Video node. If the preview fails, the upload still succeeds.

Read Video From S3

Category: image

Input:

  • s3_key (STRING): Full object key in bucket, e.g. videos/clip.mp4
  • s3_source (optional dropdown): auto (try in order) (default) or one key set name

Output:

  • video_path (STRING): local path of the downloaded file, e.g. for VideoHelperSuite's Load Video (Path), which gives frames, frame count, audio and video info
  • video (VIDEO): native ComfyUI video, e.g. for Concatenate Video or Save Video To S3

Behavior:

  • auto / named key set: same as Read Image From S3
  • Downloads into ComfyUI's temp folder under a new random name and keeps the file, because both outputs read it after the node returns. ComfyUI empties the temp folder on startup.
  • The file is not decoded here; a key without a video extension is saved as .mp4
  • Re-runs only when s3_key or s3_source changes (same caching as Read Image From S3)

Is Mask Empty

Category: image

Input:

  • mask (MASK)

Output:

  • BOOLEAN

Supported inputs for Read Image From S3

Direct image decode with Pillow

  • .png
  • .jpg
  • .jpeg
  • .bmp
  • .webp
  • .tiff

HEIC / HEIF image decode with Pillow + pillow-heif

  • .heic
  • .heif
  • mislabeled files where the extension is image-like but the file contents are actually HEIC/HEIF
  • if the HEIC/HEIF file is animated, the first frame is used

First-frame fallback via ffmpeg

  • .mp4
  • .mov
  • .webm
  • .mkv
  • .avi
  • mislabeled files where the extension is image-like but the file contents are actually video

Required IAM permissions

  • s3:GetObject
  • s3:PutObject
  • s3:ListBucket (recommended)

Troubleshooting

  • No S3 storage is configured

    • Set at least one key set (e.g. S3_BUCKET) in .env and restart ComfyUI.
  • S3 source '...' is not configured

    • The workflow picked a key set name that is not in .env (renamed or removed). Pick another one in the dropdown.
  • s3_key cannot be empty

    • Provide a full object key including folder and filename.
  • Please provide an absolute local video path

    • Pass an absolute path in video_path.
  • Local video file not found

    • Confirm the file exists on disk and ComfyUI has access.
  • ffmpeg is required to decode video/live photo inputs, but it was not found in PATH

    • Install ffmpeg and make sure the ComfyUI process can find it.
  • HEIC/HEIF files still cannot be read

    • Install pillow-heif in the same Python environment as ComfyUI.
    • If the file is not really HEIC/HEIF but a video-like container, keep ffmpeg installed as fallback.

Version

Current version: 3.2.0