From eeee0f5b1b722abbbf3810d993a50e96fb0d6756 Mon Sep 17 00:00:00 2001
From: "B. Bergeron" <me@bbergeron.xyz>
Date: Tue, 12 Aug 2025 19:32:28 -0400
Subject: [PATCH 01/21] Add local Docker support

---
 .dockerignore      | 31 +++++++++++++++++
 .gitignore         |  1 +
 Dockerfile         | 84 ++++++++++++++++++++++++++++++++++++++++++++++
 docker-compose.yml | 42 +++++++++++++++++++++++
 entrypoint.sh      | 76 +++++++++++++++++++++++++++++++++++++++++
 5 files changed, 234 insertions(+)
 create mode 100644 .dockerignore
 create mode 100644 Dockerfile
 create mode 100644 docker-compose.yml
 create mode 100755 entrypoint.sh

diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 000000000..ca3feff67
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,31 @@
+# This file should remain in sync with .gitignore. If you need to make changes,
+# please add a comment explaining why. For items that must be removed, comment
+# them out instead of deleting them.
+__pycache__/
+*.py[cod]
+/output/
+/input/
+# This file prevents the image from building and would be overwritten by the
+# /data volume in any case.
+#!/input/example.png
+/models/
+/temp/
+/custom_nodes/
+!custom_nodes/example_node.py.example
+extra_model_paths.yaml
+/.vs
+.vscode/
+.idea/
+venv/
+.venv/
+/web/extensions/*
+!/web/extensions/logging.js.example
+!/web/extensions/core/
+/tests-ui/data/object_info.json
+/user/
+*.log
+web_custom_versions/
+.DS_Store
+openapi.yaml
+filtered-openapi.yaml
+uv.lock
diff --git a/.gitignore b/.gitignore
index 4e8cea71e..847bfe03a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
+# If you modify this file, remember to update .dockerignore as well.
 __pycache__/
 *.py[cod]
 /output/
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 000000000..99d7cc70b
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,84 @@
+# Docker buildfile for the ComfyUI image, with support for hardware
+# acceleration, file ownership synchronization, custom nodes, and custom node
+# managers.
+#
+# Authors:
+# B. Bergeron <me@bbergeron.xyz>
+#
+
+# Use the recommended Python version 3.12, as specified in the README.
+FROM python:3.12.11-bookworm AS comfyui-base
+
+# Install cmake, which is an indirect installation dependencies
+RUN apt update                                      \
+	&& apt install -y --no-install-recommends cmake \
+	&& apt clean                                    \
+	&& rm -rf /var/lib/apt/lists/*
+
+# Create a mount point for user-generated data.
+RUN mkdir -p      \
+	/data/input   \
+	/data/output  \
+	/data/temp    \
+	/data/user
+
+# Create a regular user whose UID and GID will match the host user's at runtime.
+# Also create a home directory for this user (-m), as some common Python tools
+# (such as uv) interact with the user’s home directory.
+RUN useradd -m comfyui
+USER comfyui
+
+# Install ComfyUI under /comfyui.
+WORKDIR /comfyui
+
+# Set up a Python virtual environment and configure it as the default Python.
+#
+# Reasons for using a virtual environment:
+# - Some custom nodes use third-party tools like uv, which do not support
+#   user-level installations.
+# - Custom node managers may install or update dependencies as the regular user,
+#   so a global installation is not an option.
+# This leaves virtual environments as the only viable choice.
+RUN python -m venv .venv
+ENV PATH="/comfyui/.venv/bin:$PATH"
+
+# Install Python dependencies. This step is also performed automatically by the
+# entrypoint script, but doing it at build time reduces startup time on the
+# first run.
+COPY requirements.txt ./
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Install ComfyUI and link the data mount points.
+COPY . .
+RUN ln -sf /data/* .
+
+# Purely declarative: inform Docker and image users that this image is designed
+# to listen on port 8188 for the web GUI.
+EXPOSE 8188
+
+# Declare persistent volumes:
+# - /data: stores user-generated data from ComfyUI,
+# - /comfyui/.venv: stores Python data generated by the entrypoint and custom
+#   node managers,
+# - /comfyui/custom_nodes: stores custom nodes installed at runtime by custom
+#   node managers,
+# - /home/comfyui: stores data from Python packages that may write outside the
+#   virtual environment and into the user’s home directory.
+VOLUME [ "/data", "/comfyui/.venv", "/comfyui/custom_nodes", "/home/comfyui" ]
+
+# Switch back to root to run the entrypoint and ensure it is executable.
+USER root
+RUN chmod +x entrypoint.sh
+ENTRYPOINT [ "./entrypoint.sh" ]
+CMD [ "python", "./main.py" ]
+
+# Known issue: Some custom nodes require additional system dependencies, which
+# are not as easy to install as Python dependencies. If this is the case, you
+# can use the instruction below to install the required packages.
+#RUN apt update                                \
+#	&& apt install -y --no-install-recommends \
+#		package-1 \
+#		package-2 \
+#		...       \
+#	&& apt clean                              \
+#	&& rm -rf /var/lib/apt/lists/*
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 000000000..c6bf30456
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,42 @@
+# Docker Compose file to run ComfyUI locally using Docker.
+#
+# Authors:
+# B. Bergeron <me@bbergeron.xyz>
+#
+
+services:
+  comfyui:
+    container_name: comfyui
+    build: .
+
+    ports:
+      - 127.0.0.1:8188:8188
+
+    # Optional: enable GPU access for hardware acceleration.
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - capabilities: [gpu]
+    volumes:
+      # Share custom nodes and models with the container.
+      - ./custom_nodes:/comfyui/custom_nodes
+      - ./models:/comfyui/models
+      # Optional: mount the user data directory.
+      #- data:/data/
+
+    environment:
+      # Overwrite the container user's UID and GID to match the host's. This
+      # allows files created by ComfyUI to be mounted on the host without
+      # permission issues.
+      UID: 1000
+      GID: 1000
+      # Declare additional Python packages to install. Useful when a custom node
+      # pack does not properly specify all its dependencies or relies on
+      # optional dependencies.
+      #PIP_EXTRA_PACKAGES:
+
+    # Optional: Override the default command. In this case, configure ComfyUI to
+    # listen on all network interfaces (which is required when not using
+    # `network_mode=host`.)
+    command: python ./main.py --listen 0.0.0.0
diff --git a/entrypoint.sh b/entrypoint.sh
new file mode 100755
index 000000000..9b844eb1d
--- /dev/null
+++ b/entrypoint.sh
@@ -0,0 +1,76 @@
+#!/bin/sh
+
+# Entrypoint script for the ComfyUI Docker image.
+#
+# Authors:
+# B. Bergeron <me@bbergeron.xyz>
+#
+
+set -e
+
+user="comfyui"
+user_group="$user"
+
+# Allow users to specify a UID and GID matching their own, so files created
+# inside the container retain the same numeric ownership when mounted on the
+# host.
+if [ -n "$UID" ] && [ -n "$GID" ]; then
+    echo "[entrypoint] Setting user UID and GID..."
+    usermod  -u "$UID" "$user" > /dev/null
+    groupmod -g "$GID" "$user_group"
+else
+    echo "[entrypoint] Missing UID or GID environment variables; keeping default values."
+fi
+
+
+echo "[entrypoint] Changing directory ownership..."
+chown -R "$user:$user_group" /data /comfyui/custom_nodes /comfyui/.venv /home/comfyui
+
+# Add the user to the groups owning /dev/nvidia* devices to ensure CUDA access.
+# Typically, these devices belong to a single "video" group, but to be safe, we
+# add the user to each device's group individually.
+echo "[entrypoint] Adding user to GPU device groups..."
+for dev in /dev/nvidia*; do
+    # Known issue: There is no universal standard for group IDs across Linux
+    # systems, so this may add the user to unexpected groups. For example, the
+    # 'video' group on some systems uses GID 27, which corresponds to 'sudo' in
+    # the python:3.12 image. This should not cause serious problems.
+    group=$(ls -ld "$dev" | awk '{print $4}')
+    usermod -aG "$group" "$user"
+done
+
+
+# Install packages listed in ./requirements.txt, requirement files under
+# ./custom_nodes, and any specified in PIP_EXTRA_PACKAGES. Also store a hash of
+# all dependencies to detect when new or updated packages need to be installed.
+packages_hash_file="/home/comfyui/pkghash"
+
+packages_comfyui=$(cat requirements.txt)
+packages_custom=$(find custom_nodes -name requirements.txt -exec cat {} \;)
+packages_extras=$(echo "$PIP_EXTRA_PACKAGES" | tr ' ' '\n')
+
+current_hash=$(
+    {
+        echo "$packages_comfyui";
+        echo "$packages_custom";
+        echo "$packages_extras"
+    } | sort | sha256sum | awk '{print $1}'
+)
+
+if [ ! -f "$packages_hash_file" ] || [ "$current_hash" != "$(cat $packages_hash_file)" ]; then
+    echo "[entrypoint] Installing new python dependencies..."
+    reqs="-r requirements.txt"
+    for req in custom_nodes/*/requirements.txt; do
+        [ -f "$req" ] && reqs="$reqs -r $req"
+    done
+
+    su -c "pip install -q --disable-pip-version-check --no-cache-dir $reqs $PIP_EXTRA_PACKAGES" comfyui
+    echo "$current_hash" > "$packages_hash_file"
+else
+    echo "[entrypoint] Requirements unchanged, skipping install"
+fi
+
+
+# Run command as comfyui
+echo "[entrypoint] Running command"
+exec su -c "$*" comfyui

From e7ebda4b6172244301933e253150b0e191840dd9 Mon Sep 17 00:00:00 2001
From: "B. Bergeron" <me@bbergeron.xyz>
Date: Wed, 13 Aug 2025 10:36:35 -0400
Subject: [PATCH 02/21] Add instructions for Docker installation

---
 README.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/README.md b/README.md
index 6d09758c0..4bee8c258 100644
--- a/README.md
+++ b/README.md
@@ -46,6 +46,12 @@ ComfyUI lets you design and execute advanced stable diffusion pipelines using a
 - Get the latest commits and completely portable.
 - Available on Windows.
 
+#### [Docker Install](#running-with-docker)
+- Run ComfyUI inside an isolated Docker container
+- Most secure way to run ComfyUI and custom node packs
+- Requires Docker and Docker Compose
+- Supports NVIDIA GPUs (Not tested on other hardware.)
+
 #### [Manual Install](#manual-install-windows-linux)
 Supports all operating systems and GPU types (NVIDIA, AMD, Intel, Apple Silicon, Ascend).
 
@@ -350,6 +356,24 @@ For models compatible with Iluvatar Extension for PyTorch. Here's a step-by-step
 | `--enable-manager-legacy-ui` | Use the legacy manager UI instead of the new UI (requires `--enable-manager`) |
 | `--disable-manager-ui` | Disable the manager UI and endpoints while keeping background features like security checks and scheduled installation completion (requires `--enable-manager`) |
 
+## Running with Docker
+
+Start by installing Docker and Docker Compose on your host. Next, edit
+`docker-compose.yaml` and update the `UID` and `GID` variables to match your
+user. Additional fields are documented in the file for further customization.
+
+Once ready, build and run the image locally:
+
+```
+docker compose build
+docker compose up
+```
+
+To stop and remove the container along with its volumes, run:
+
+```
+docker compose down -v
+```
 
 # Running
 

From 847e3cc3a262ba42c5207c342107ae00bfa178f7 Mon Sep 17 00:00:00 2001
From: "B. Bergeron" <me@bbergeron.xyz>
Date: Wed, 13 Aug 2025 11:14:54 -0400
Subject: [PATCH 03/21] Persist models installed by model managers

---
 Dockerfile    | 3 ++-
 entrypoint.sh | 7 ++++++-
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/Dockerfile b/Dockerfile
index 99d7cc70b..bbde988ae 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -62,9 +62,10 @@ EXPOSE 8188
 #   node managers,
 # - /comfyui/custom_nodes: stores custom nodes installed at runtime by custom
 #   node managers,
+# - /comfyui/models: Stores models installed by model managers,
 # - /home/comfyui: stores data from Python packages that may write outside the
 #   virtual environment and into the user’s home directory.
-VOLUME [ "/data", "/comfyui/.venv", "/comfyui/custom_nodes", "/home/comfyui" ]
+VOLUME [ "/data", "/comfyui/.venv", "/comfyui/custom_nodes", "/comfyui/models", "/home/comfyui" ]
 
 # Switch back to root to run the entrypoint and ensure it is executable.
 USER root
diff --git a/entrypoint.sh b/entrypoint.sh
index 9b844eb1d..cbaec72f9 100755
--- a/entrypoint.sh
+++ b/entrypoint.sh
@@ -24,7 +24,12 @@ fi
 
 
 echo "[entrypoint] Changing directory ownership..."
-chown -R "$user:$user_group" /data /comfyui/custom_nodes /comfyui/.venv /home/comfyui
+chown -R "$user:$user_group" \
+    /data                    \
+    /comfyui/custom_nodes    \
+    /comfyui/models          \
+    /comfyui/.venv           \
+    /home/comfyui
 
 # Add the user to the groups owning /dev/nvidia* devices to ensure CUDA access.
 # Typically, these devices belong to a single "video" group, but to be safe, we

From 4f12985e45489705b2552ce090a6992c774857ad Mon Sep 17 00:00:00 2001
From: "B. Bergeron" <me@bbergeron.xyz>
Date: Wed, 13 Aug 2025 11:28:57 -0400
Subject: [PATCH 04/21] Install extra system dependencies at build-time

---
 Dockerfile         | 28 ++++++++++++----------------
 docker-compose.yml |  8 ++++++--
 2 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/Dockerfile b/Dockerfile
index bbde988ae..950b4eb06 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -9,11 +9,10 @@
 # Use the recommended Python version 3.12, as specified in the README.
 FROM python:3.12.11-bookworm AS comfyui-base
 
+ARG APT_EXTRA_PACKAGES
+
 # Install cmake, which is an indirect installation dependencies
-RUN apt update                                      \
-	&& apt install -y --no-install-recommends cmake \
-	&& apt clean                                    \
-	&& rm -rf /var/lib/apt/lists/*
+RUN apt update && apt install -y --no-install-recommends cmake
 
 # Create a mount point for user-generated data.
 RUN mkdir -p      \
@@ -67,19 +66,16 @@ EXPOSE 8188
 #   virtual environment and into the user’s home directory.
 VOLUME [ "/data", "/comfyui/.venv", "/comfyui/custom_nodes", "/comfyui/models", "/home/comfyui" ]
 
-# Switch back to root to run the entrypoint and ensure it is executable.
+# Switch back to root to run the entrypoint and to install additional system
+# dependencies
 USER root
+
+# Install additional system dependencies
+RUN apt install -y --no-install-recommends $APT_EXTRA_PACKAGES \
+	&& apt clean                                               \
+	&& rm -rf /var/lib/apt/lists/*
+
+# Configure entrypoint
 RUN chmod +x entrypoint.sh
 ENTRYPOINT [ "./entrypoint.sh" ]
 CMD [ "python", "./main.py" ]
-
-# Known issue: Some custom nodes require additional system dependencies, which
-# are not as easy to install as Python dependencies. If this is the case, you
-# can use the instruction below to install the required packages.
-#RUN apt update                                \
-#	&& apt install -y --no-install-recommends \
-#		package-1 \
-#		package-2 \
-#		...       \
-#	&& apt clean                              \
-#	&& rm -rf /var/lib/apt/lists/*
diff --git a/docker-compose.yml b/docker-compose.yml
index c6bf30456..8e4ff0e67 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -7,7 +7,11 @@
 services:
   comfyui:
     container_name: comfyui
-    build: .
+    build:
+      context: .
+      args:
+        # Declare additional system dependencies for custom nodes
+        APT_EXTRA_PACKAGES:
 
     ports:
       - 127.0.0.1:8188:8188
@@ -34,7 +38,7 @@ services:
       # Declare additional Python packages to install. Useful when a custom node
       # pack does not properly specify all its dependencies or relies on
       # optional dependencies.
-      #PIP_EXTRA_PACKAGES:
+      PIP_EXTRA_PACKAGES:
 
     # Optional: Override the default command. In this case, configure ComfyUI to
     # listen on all network interfaces (which is required when not using

From 6572cbb61d53069298ee00fdd135aff5c56265af Mon Sep 17 00:00:00 2001
From: "B. Bergeron" <me@bbergeron.xyz>
Date: Wed, 13 Aug 2025 11:31:33 -0400
Subject: [PATCH 05/21] Inform user that installation might take a while

---
 entrypoint.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/entrypoint.sh b/entrypoint.sh
index cbaec72f9..d59369cf7 100755
--- a/entrypoint.sh
+++ b/entrypoint.sh
@@ -63,7 +63,7 @@ current_hash=$(
 )
 
 if [ ! -f "$packages_hash_file" ] || [ "$current_hash" != "$(cat $packages_hash_file)" ]; then
-    echo "[entrypoint] Installing new python dependencies..."
+    echo "[entrypoint] Installing new python dependencies, this might take a while..."
     reqs="-r requirements.txt"
     for req in custom_nodes/*/requirements.txt; do
         [ -f "$req" ] && reqs="$reqs -r $req"

From 5b27c661c6766e3636e7d3fdd6f3cb02e5797790 Mon Sep 17 00:00:00 2001
From: "B. Bergeron" <me@bbergeron.xyz>
Date: Wed, 13 Aug 2025 12:03:27 -0400
Subject: [PATCH 06/21] Update ownership of /comfyui to comfyui user

---
 entrypoint.sh | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/entrypoint.sh b/entrypoint.sh
index d59369cf7..7f8661348 100755
--- a/entrypoint.sh
+++ b/entrypoint.sh
@@ -26,9 +26,7 @@ fi
 echo "[entrypoint] Changing directory ownership..."
 chown -R "$user:$user_group" \
     /data                    \
-    /comfyui/custom_nodes    \
-    /comfyui/models          \
-    /comfyui/.venv           \
+    /comfyui                 \
     /home/comfyui
 
 # Add the user to the groups owning /dev/nvidia* devices to ensure CUDA access.

From 41b4c3ea73d763e2f6f807d99ebdd285f7971287 Mon Sep 17 00:00:00 2001
From: "B. Bergeron" <me@bbergeron.xyz>
Date: Thu, 14 Aug 2025 11:17:49 -0400
Subject: [PATCH 07/21] Force LF eol for entrypoint.sh

---
 .gitattributes | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.gitattributes b/.gitattributes
index 5b3c15bb4..c68ee9205 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -1,3 +1,6 @@
 /web/assets/** linguist-generated
 /web/** linguist-vendored
 comfy_api_nodes/apis/__init__.py linguist-generated
+# Force LF eol for Docker entrypoint (fix "exec: no such file or directory"
+# error with CRLF checkouts)
+entrypoint.sh text eol=lf

From 7419345b76d15f92640ccb4e0fffd6772f43fdb2 Mon Sep 17 00:00:00 2001
From: "B. Bergeron" <me@bbergeron.xyz>
Date: Tue, 19 Aug 2025 17:44:41 -0400
Subject: [PATCH 08/21] Remove superfluous command-separators

---
 entrypoint.sh | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/entrypoint.sh b/entrypoint.sh
index 7f8661348..df1e275d0 100755
--- a/entrypoint.sh
+++ b/entrypoint.sh
@@ -54,8 +54,8 @@ packages_extras=$(echo "$PIP_EXTRA_PACKAGES" | tr ' ' '\n')
 
 current_hash=$(
     {
-        echo "$packages_comfyui";
-        echo "$packages_custom";
+        echo "$packages_comfyui"
+        echo "$packages_custom"
         echo "$packages_extras"
     } | sort | sha256sum | awk '{print $1}'
 )

From aba97d6adaa3de3ee0d81ddc095e13dfe83f7e22 Mon Sep 17 00:00:00 2001
From: "B. Bergeron" <me@bbergeron.xyz>
Date: Tue, 19 Aug 2025 18:05:58 -0400
Subject: [PATCH 09/21] Add @bbergeron0 to CODEOWNER

---
 Dockerfile         | 4 ----
 docker-compose.yml | 4 ----
 entrypoint.sh      | 4 ----
 3 files changed, 12 deletions(-)

diff --git a/Dockerfile b/Dockerfile
index 950b4eb06..592b6a4fa 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -1,10 +1,6 @@
 # Docker buildfile for the ComfyUI image, with support for hardware
 # acceleration, file ownership synchronization, custom nodes, and custom node
 # managers.
-#
-# Authors:
-# B. Bergeron <me@bbergeron.xyz>
-#
 
 # Use the recommended Python version 3.12, as specified in the README.
 FROM python:3.12.11-bookworm AS comfyui-base
diff --git a/docker-compose.yml b/docker-compose.yml
index 8e4ff0e67..f7263970c 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -1,8 +1,4 @@
 # Docker Compose file to run ComfyUI locally using Docker.
-#
-# Authors:
-# B. Bergeron <me@bbergeron.xyz>
-#
 
 services:
   comfyui:
diff --git a/entrypoint.sh b/entrypoint.sh
index df1e275d0..f059293e8 100755
--- a/entrypoint.sh
+++ b/entrypoint.sh
@@ -1,10 +1,6 @@
 #!/bin/sh
 
 # Entrypoint script for the ComfyUI Docker image.
-#
-# Authors:
-# B. Bergeron <me@bbergeron.xyz>
-#
 
 set -e
 

From 36e19df686992bd1940da256b281f838260a3d0e Mon Sep 17 00:00:00 2001
From: "B. Bergeron" <me@bbergeron.xyz>
Date: Sun, 24 Aug 2025 20:28:37 -0400
Subject: [PATCH 10/21] Use recommended compose file name for Docker Compose

---
 README.md                          | 2 +-
 docker-compose.yml => compose.yaml | 0
 2 files changed, 1 insertion(+), 1 deletion(-)
 rename docker-compose.yml => compose.yaml (100%)

diff --git a/README.md b/README.md
index 4bee8c258..83335efa6 100644
--- a/README.md
+++ b/README.md
@@ -359,7 +359,7 @@ For models compatible with Iluvatar Extension for PyTorch. Here's a step-by-step
 ## Running with Docker
 
 Start by installing Docker and Docker Compose on your host. Next, edit
-`docker-compose.yaml` and update the `UID` and `GID` variables to match your
+`compose.yaml` and update the `UID` and `GID` variables to match your
 user. Additional fields are documented in the file for further customization.
 
 Once ready, build and run the image locally:
diff --git a/docker-compose.yml b/compose.yaml
similarity index 100%
rename from docker-compose.yml
rename to compose.yaml

From 477f3304158d10dd63292ffc3961eb891e234c4d Mon Sep 17 00:00:00 2001
From: "B. Bergeron" <me@bbergeron.xyz>
Date: Mon, 25 Aug 2025 22:21:07 -0400
Subject: [PATCH 11/21] Use stable apt-get CLI interface instead of apt

---
 Dockerfile | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Dockerfile b/Dockerfile
index 592b6a4fa..ce43bfbac 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -8,7 +8,7 @@ FROM python:3.12.11-bookworm AS comfyui-base
 ARG APT_EXTRA_PACKAGES
 
 # Install cmake, which is an indirect installation dependencies
-RUN apt update && apt install -y --no-install-recommends cmake
+RUN apt-get update && apt-get install -y --no-install-recommends cmake
 
 # Create a mount point for user-generated data.
 RUN mkdir -p      \
@@ -67,8 +67,8 @@ VOLUME [ "/data", "/comfyui/.venv", "/comfyui/custom_nodes", "/comfyui/models",
 USER root
 
 # Install additional system dependencies
-RUN apt install -y --no-install-recommends $APT_EXTRA_PACKAGES \
-	&& apt clean                                               \
+RUN apt-get install -y --no-install-recommends $APT_EXTRA_PACKAGES \
+	&& apt-get clean                                               \
 	&& rm -rf /var/lib/apt/lists/*
 
 # Configure entrypoint

From 357f89a4bfe6b94c46eac6604f2114967257c0bf Mon Sep 17 00:00:00 2001
From: "B. Bergeron" <me@bbergeron.xyz>
Date: Mon, 25 Aug 2025 22:56:35 -0400
Subject: [PATCH 12/21] Fix permission issue on legacy builds

---
 Dockerfile | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/Dockerfile b/Dockerfile
index ce43bfbac..11e1f6e01 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -21,10 +21,16 @@ RUN mkdir -p      \
 # Also create a home directory for this user (-m), as some common Python tools
 # (such as uv) interact with the user’s home directory.
 RUN useradd -m comfyui
-USER comfyui
 
-# Install ComfyUI under /comfyui.
+# Install ComfyUI under /comfyui and set folder ownership to the comfyui user.
+# With the legacy Docker builder (DOCKER_BUILDKIT=0), WORKDIR always creates missing
+# directories as root (even if a different USER is active). To ensure the comfyui user
+# can write inside, ownership must be fixed manually.
 WORKDIR /comfyui
+RUN chown comfyui:comfyui .
+
+# Install ComfyUI as ComfyUI
+USER comfyui
 
 # Set up a Python virtual environment and configure it as the default Python.
 #

From e1cf4f7420b1a1badc052ae05af99af79fc062f2 Mon Sep 17 00:00:00 2001
From: "B. Bergeron" <me@bbergeron.xyz>
Date: Mon, 25 Aug 2025 23:12:14 -0400
Subject: [PATCH 13/21] Don't rebuild whole image when APT_EXTRA_PACKAGES
 changes

---
 Dockerfile | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/Dockerfile b/Dockerfile
index 11e1f6e01..e124ca428 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -5,8 +5,6 @@
 # Use the recommended Python version 3.12, as specified in the README.
 FROM python:3.12.11-bookworm AS comfyui-base
 
-ARG APT_EXTRA_PACKAGES
-
 # Install cmake, which is an indirect installation dependencies
 RUN apt-get update && apt-get install -y --no-install-recommends cmake
 
@@ -72,12 +70,13 @@ VOLUME [ "/data", "/comfyui/.venv", "/comfyui/custom_nodes", "/comfyui/models",
 # dependencies
 USER root
 
-# Install additional system dependencies
-RUN apt-get install -y --no-install-recommends $APT_EXTRA_PACKAGES \
-	&& apt-get clean                                               \
-	&& rm -rf /var/lib/apt/lists/*
-
 # Configure entrypoint
 RUN chmod +x entrypoint.sh
 ENTRYPOINT [ "./entrypoint.sh" ]
 CMD [ "python", "./main.py" ]
+
+# Install additional system dependencies
+ARG APT_EXTRA_PACKAGES
+RUN apt-get install -y --no-install-recommends $APT_EXTRA_PACKAGES \
+	&& apt-get clean                                               \
+	&& rm -rf /var/lib/apt/lists/*

From 174d91c9edccb0083c618eb00db58353e725db98 Mon Sep 17 00:00:00 2001
From: "B. Bergeron" <me@bbergeron.xyz>
Date: Tue, 9 Sep 2025 23:07:37 -0400
Subject: [PATCH 14/21] Improved documentation

---
 README.md | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 83335efa6..755922efd 100644
--- a/README.md
+++ b/README.md
@@ -358,20 +358,24 @@ For models compatible with Iluvatar Extension for PyTorch. Here's a step-by-step
 
 ## Running with Docker
 
-Start by installing Docker and Docker Compose on your host. Next, edit
-`compose.yaml` and update the `UID` and `GID` variables to match your
-user. Additional fields are documented in the file for further customization.
+Start by installing Docker, Docker Compose, and the NVIDIA Container Toolkit on
+your host. Next, edit `compose.yaml` and update the `UID` and `GID` variables to
+match your user. Additional fields are documented in the file for further
+customization.
 
 Once ready, build and run the image locally:
 
-```
+```shell
+# (Re)build the Docker image. Run this before the first start, after updating
+# ComfyUI, or after changing any build arguments in `compose.yaml`.
 docker compose build
+# Start ComfyUI. This reuses the most recently built image.
 docker compose up
 ```
 
 To stop and remove the container along with its volumes, run:
 
-```
+```shell
 docker compose down -v
 ```
 

From 2c859e95589b1539eb61a2653292f75165b6a99f Mon Sep 17 00:00:00 2001
From: "B. Bergeron" <me@bbergeron.xyz>
Date: Tue, 9 Sep 2025 23:35:24 -0400
Subject: [PATCH 15/21] Remove superfluous interface binding

---
 compose.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/compose.yaml b/compose.yaml
index f7263970c..52087f337 100644
--- a/compose.yaml
+++ b/compose.yaml
@@ -10,7 +10,7 @@ services:
         APT_EXTRA_PACKAGES:
 
     ports:
-      - 127.0.0.1:8188:8188
+      - 8188:8188
 
     # Optional: enable GPU access for hardware acceleration.
     deploy:

From b4dcbdfac7023f4a05a483c87c1eb3af2d092f1d Mon Sep 17 00:00:00 2001
From: "B. Bergeron" <me@bbergeron.xyz>
Date: Mon, 20 Oct 2025 20:09:47 -0400
Subject: [PATCH 16/21] Remove unused "AS" docker statement

---
 Dockerfile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Dockerfile b/Dockerfile
index e124ca428..6dd61a2bd 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -3,7 +3,7 @@
 # managers.
 
 # Use the recommended Python version 3.12, as specified in the README.
-FROM python:3.12.11-bookworm AS comfyui-base
+FROM python:3.12.11-bookworm
 
 # Install cmake, which is an indirect installation dependencies
 RUN apt-get update && apt-get install -y --no-install-recommends cmake

From 6c9110564b5b7ced8c9d18922b2e5f4daeb69fc5 Mon Sep 17 00:00:00 2001
From: "B. Bergeron" <me@bbergeron.xyz>
Date: Sat, 10 Jan 2026 16:58:21 -0500
Subject: [PATCH 17/21] Pin base image version to 3.12.12-trixie + document
 version choice

---
 Dockerfile | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/Dockerfile b/Dockerfile
index 6dd61a2bd..660d82f75 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -2,8 +2,14 @@
 # acceleration, file ownership synchronization, custom nodes, and custom node
 # managers.
 
-# Use the recommended Python version 3.12, as specified in the README.
-FROM python:3.12.11-bookworm
+# While Python 3.13 is well supported by ComfyUI, some older custom node packs
+# may not work correctly with this version, which is why we're staying on Python
+# 3.12 for now.
+#
+# Users are free to try different base Python image tags (e.g., 3.13, alpine,
+# *-slim), but for maintainability, only one base version is officially
+# supported at a time.
+FROM python:3.12.12-trixie
 
 # Install cmake, which is an indirect installation dependencies
 RUN apt-get update && apt-get install -y --no-install-recommends cmake

From c804c0c12e33ee83e8d41ed71af99936461ad806 Mon Sep 17 00:00:00 2001
From: "B. Bergeron" <me@bbergeron.xyz>
Date: Sat, 10 Jan 2026 17:54:25 -0500
Subject: [PATCH 18/21] Always update Python dependencies + don't hide pip logs

---
 entrypoint.sh | 44 +++++++++++++-------------------------------
 1 file changed, 13 insertions(+), 31 deletions(-)

diff --git a/entrypoint.sh b/entrypoint.sh
index f059293e8..285b460d6 100755
--- a/entrypoint.sh
+++ b/entrypoint.sh
@@ -38,37 +38,19 @@ for dev in /dev/nvidia*; do
     usermod -aG "$group" "$user"
 done
 
-
-# Install packages listed in ./requirements.txt, requirement files under
-# ./custom_nodes, and any specified in PIP_EXTRA_PACKAGES. Also store a hash of
-# all dependencies to detect when new or updated packages need to be installed.
-packages_hash_file="/home/comfyui/pkghash"
-
-packages_comfyui=$(cat requirements.txt)
-packages_custom=$(find custom_nodes -name requirements.txt -exec cat {} \;)
-packages_extras=$(echo "$PIP_EXTRA_PACKAGES" | tr ' ' '\n')
-
-current_hash=$(
-    {
-        echo "$packages_comfyui"
-        echo "$packages_custom"
-        echo "$packages_extras"
-    } | sort | sha256sum | awk '{print $1}'
-)
-
-if [ ! -f "$packages_hash_file" ] || [ "$current_hash" != "$(cat $packages_hash_file)" ]; then
-    echo "[entrypoint] Installing new python dependencies, this might take a while..."
-    reqs="-r requirements.txt"
-    for req in custom_nodes/*/requirements.txt; do
-        [ -f "$req" ] && reqs="$reqs -r $req"
-    done
-
-    su -c "pip install -q --disable-pip-version-check --no-cache-dir $reqs $PIP_EXTRA_PACKAGES" comfyui
-    echo "$current_hash" > "$packages_hash_file"
-else
-    echo "[entrypoint] Requirements unchanged, skipping install"
-fi
-
+# Install or update the Python dependencies defined by ComfyUI (or any installed
+# custom node) and also install any user-defined dependencies specified in
+# PIP_EXTRA_PACKAGES.
+echo "[entrypoint] Updating Python dependencies..."
+su -c "
+   pip install                      \\
+        --no-cache-dir              \\
+        --disable-pip-version-check \\
+        -r requirements.txt         \\
+        $(find custom_nodes -mindepth 2 -maxdepth 2 -type f -name requirements.txt -printf "-r '%p' ") \\
+        $PIP_EXTRA_PACKAGES
+" comfyui \
+    || echo "[entrypoint] Failed to install dependencies, starting anyway" >&2
 
 # Run command as comfyui
 echo "[entrypoint] Running command"

From c4c388ffc8a9530dcfcbee1b6862632313ab34d0 Mon Sep 17 00:00:00 2001
From: "B. Bergeron" <me@bbergeron.xyz>
Date: Sat, 10 Jan 2026 17:55:33 -0500
Subject: [PATCH 19/21] Improve documentation regarding numerical ownership

---
 entrypoint.sh | 22 ++++++++++++++--------
 1 file changed, 14 insertions(+), 8 deletions(-)

diff --git a/entrypoint.sh b/entrypoint.sh
index 285b460d6..a0aabb65d 100755
--- a/entrypoint.sh
+++ b/entrypoint.sh
@@ -18,22 +18,28 @@ else
     echo "[entrypoint] Missing UID or GID environment variables; keeping default values."
 fi
 
-
+# Changing a user's UID and GID revokes that user's access to files owned by the
+# original UID/GID. To preserve access to runtime data, the ownership of those
+# directories must be updated recursively so that their numeric owner matches
+# the user's new UID and GID.
 echo "[entrypoint] Changing directory ownership..."
 chown -R "$user:$user_group" \
     /data                    \
     /comfyui                 \
     /home/comfyui
 
-# Add the user to the groups owning /dev/nvidia* devices to ensure CUDA access.
-# Typically, these devices belong to a single "video" group, but to be safe, we
-# add the user to each device's group individually.
+# To use CUDA and other NVIDIA features, regular users must belong to the group
+# that owns the /dev/nvidia* device files -- typically the video group.
+#
+# Known issue: Because these device files are mounted from the host system,
+# there's no guarantee that the device's group ID will match the intended group
+# inside the container. For example, the video group might be mapped to GID 27
+# on the host, which corresponds to the sudo group in the python:3.12 image.
+# This shouldn't cause major problems, and given the lack of a universal
+# standard for system GIDs, there isn't much we can realistically change to
+# address this issue.
 echo "[entrypoint] Adding user to GPU device groups..."
 for dev in /dev/nvidia*; do
-    # Known issue: There is no universal standard for group IDs across Linux
-    # systems, so this may add the user to unexpected groups. For example, the
-    # 'video' group on some systems uses GID 27, which corresponds to 'sudo' in
-    # the python:3.12 image. This should not cause serious problems.
     group=$(ls -ld "$dev" | awk '{print $4}')
     usermod -aG "$group" "$user"
 done

From 7795a4e86c641d288c723b017a9df32f6ab329d5 Mon Sep 17 00:00:00 2001
From: "B. Bergeron" <me@bbergeron.xyz>
Date: Sat, 10 Jan 2026 18:17:09 -0500
Subject: [PATCH 20/21] Improve documentation regarding pip install step

---
 Dockerfile | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/Dockerfile b/Dockerfile
index 660d82f75..bc4be83dd 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -47,11 +47,15 @@ USER comfyui
 RUN python -m venv .venv
 ENV PATH="/comfyui/.venv/bin:$PATH"
 
-# Install Python dependencies. This step is also performed automatically by the
-# entrypoint script, but doing it at build time reduces startup time on the
-# first run.
-COPY requirements.txt ./
-RUN pip install --no-cache-dir -r requirements.txt
+# Install ComfyUI's Python dependencies. Although dependency keeping is also
+# performed at startup, building ComfyUI's base dependencies into the image
+# significantly speeds up each containers' first run.
+#
+# Since this step takes a long time to complete, it's performed early to take
+# advantage of Docker's build cache, thereby accelerating subsequent builds.
+COPY requirements.txt manager_requirements.txt ./
+RUN pip install --no-cache-dir --disable-pip-version-check \
+    -r requirements.txt
 
 # Install ComfyUI and link the data mount points.
 COPY . .

From fa71050a0749a4a69a7696eeac3374e537f2ee39 Mon Sep 17 00:00:00 2001
From: "B. Bergeron" <me@bbergeron.xyz>
Date: Sat, 10 Jan 2026 19:03:47 -0500
Subject: [PATCH 21/21] Split data volume

---
 Dockerfile    | 31 ++++++++++++-------------------
 compose.yaml  | 10 +++++++---
 entrypoint.sh |  1 -
 3 files changed, 19 insertions(+), 23 deletions(-)

diff --git a/Dockerfile b/Dockerfile
index bc4be83dd..ccdaa4be3 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -14,13 +14,6 @@ FROM python:3.12.12-trixie
 # Install cmake, which is an indirect installation dependencies
 RUN apt-get update && apt-get install -y --no-install-recommends cmake
 
-# Create a mount point for user-generated data.
-RUN mkdir -p      \
-	/data/input   \
-	/data/output  \
-	/data/temp    \
-	/data/user
-
 # Create a regular user whose UID and GID will match the host user's at runtime.
 # Also create a home directory for this user (-m), as some common Python tools
 # (such as uv) interact with the user’s home directory.
@@ -57,24 +50,24 @@ COPY requirements.txt manager_requirements.txt ./
 RUN pip install --no-cache-dir --disable-pip-version-check \
     -r requirements.txt
 
-# Install ComfyUI and link the data mount points.
+# Install ComfyUI
 COPY . .
-RUN ln -sf /data/* .
 
 # Purely declarative: inform Docker and image users that this image is designed
 # to listen on port 8188 for the web GUI.
 EXPOSE 8188
 
-# Declare persistent volumes:
-# - /data: stores user-generated data from ComfyUI,
-# - /comfyui/.venv: stores Python data generated by the entrypoint and custom
-#   node managers,
-# - /comfyui/custom_nodes: stores custom nodes installed at runtime by custom
-#   node managers,
-# - /comfyui/models: Stores models installed by model managers,
-# - /home/comfyui: stores data from Python packages that may write outside the
-#   virtual environment and into the user’s home directory.
-VOLUME [ "/data", "/comfyui/.venv", "/comfyui/custom_nodes", "/comfyui/models", "/home/comfyui" ]
+# Declare persistent volumes. We assign one volume per data directory to match
+# ComfyUI’s natural file layout and to let users selectively choose which
+# directories they want to mount.
+VOLUME /comfyui/.venv
+VOLUME /comfyui/custom_nodes
+VOLUME /comfyui/input
+VOLUME /comfyui/models
+VOLUME /comfyui/output
+VOLUME /comfyui/temp
+VOLUME /comfyui/user
+VOLUME /home/comfyui
 
 # Switch back to root to run the entrypoint and to install additional system
 # dependencies
diff --git a/compose.yaml b/compose.yaml
index 52087f337..d242b05a4 100644
--- a/compose.yaml
+++ b/compose.yaml
@@ -19,11 +19,15 @@ services:
           devices:
             - capabilities: [gpu]
     volumes:
-      # Share custom nodes and models with the container.
       - ./custom_nodes:/comfyui/custom_nodes
       - ./models:/comfyui/models
-      # Optional: mount the user data directory.
-      #- data:/data/
+
+      # (Optional) Mount host ComfyUI data directories
+      #
+      #- ./input:/comfyui/input
+      #- ./output:/comfyui/output
+      #- ./temp:/comfyui/temp
+      #- ./user:/comfyui/user
 
     environment:
       # Overwrite the container user's UID and GID to match the host's. This
diff --git a/entrypoint.sh b/entrypoint.sh
index a0aabb65d..37e576452 100755
--- a/entrypoint.sh
+++ b/entrypoint.sh
@@ -24,7 +24,6 @@ fi
 # the user's new UID and GID.
 echo "[entrypoint] Changing directory ownership..."
 chown -R "$user:$user_group" \
-    /data                    \
     /comfyui                 \
     /home/comfyui