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.
Nodes (5)
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-heifis 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
- Clone into ComfyUI custom nodes:
cd /ComfyUI/custom_nodes
git clone https://github.com/lakkiy/ComfyUI-RWImageS3.git
cd ComfyUI-RWImageS3
- 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.
-
Ensure
ffmpegis available inPATHif you wantRead Image From S3to support:- files whose extension says
.png/.jpgbut whose actual contents are video - Apple Live Photo companion videos (
.mov) - other video inputs where only the first frame should be used
- files whose extension says
-
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
BUCKETis required; a set without it is ignored.REGION(defaultus-east-1) andENDPOINT_URLare optional.NAMEis what shows up in the node'ss3_sourcedropdown (defaultdefaultfor the first set,s3_<N>for the others). Names must be unique; duplicates get a(2)suffix.autotries the first set, thenS3_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, ... |
- Restart ComfyUI.
Nodes
Read Image From S3
Category: image
Input:
s3_key(STRING): Full object key in bucket, e.g.images/cat.pngs3_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-heifis 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
ffmpegto extract the first frame - This means it can handle:
- normal images
- animated images
- HEIC/HEIF uploads
- files mislabeled as
.png/.jpgin 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.pngs3_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_keyextension (e.g.image/png), so a bucket served straight to browsers shows it - 1 image: uploaded to
s3_keyas-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.mp4video(VIDEO, optional): native ComfyUI video, e.g. from Create Video or Load Video. Written as mp4, mkv or webm based on thes3_keyextension (anything else is written as mp4).filenames(VHS_FILENAMES, optional): theFilenamesoutput 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.mp4s3_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
faststarton, remuxes mp4/mov withffmpeg -c copy -movflags +faststartinto 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. UsesffmpegfromPATH, elseimageio-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_keyextension (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.mp4s3_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 infovideo(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_keyors3_sourcechanges (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:GetObjects3:PutObjects3:ListBucket(recommended)
Troubleshooting
-
No S3 storage is configured- Set at least one key set (e.g.
S3_BUCKET) in.envand restart ComfyUI.
- Set at least one key set (e.g.
-
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.
- The workflow picked a key set name that is not in
-
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.
- Pass an absolute path in
-
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
ffmpegand make sure the ComfyUI process can find it.
- Install
-
HEIC/HEIF files still cannot be read
- Install
pillow-heifin the same Python environment as ComfyUI. - If the file is not really HEIC/HEIF but a video-like container, keep
ffmpeginstalled as fallback.
- Install
Version
Current version: 3.2.0