Run ComfyUI Workflows on Hugging Face Spaces with Gradio

Hugging Face has introduced a method to convert complex ComfyUI workflows into standalone Gradio applications, enabling them to be deployed and run for free using the serverless ZeroGPU infrastructure on Hugging Face Spaces.

Exporting ComfyUI Workflows to Python

To run a ComfyUI workflow without its node-based UI, the workflow must first be exported as a pure Python script. This is achieved using the ComfyUI-to-Python-Extension created by Peyton DeNiro.

Export Process:

  1. Install the ComfyUI to Python Extension via the Custom Nodes Manager in ComfyUI.
  2. Access the UI settings, disable the new menu, and select "Save as Script".
  3. This process generates a Python script that represents the workflow's backend logic.

Creating a Gradio Interface

Once the workflow is exported to Python, a Gradio app can be built to orchestrate the script and provide a user-friendly interface.

UI Implementation

Developers can use gr.Blocks() to define the inputs they wish to expose to the end user. For example, in a Flux[dev] Redux + Flux[dev] Depth workflow, typical exposed parameters include:

  • Text prompts
  • Structure and style images
  • Depth and style strength sliders

Integrating Logic

To make the UI functional, the exported main() function from the Python script is converted into a generation function (e.g., generate_image). Hard-coded values within the exported script are replaced with variables passed from the Gradio inputs, and the final image output node is modified to return the saved image path.

Deploying to Hugging Face Spaces

Deploying to Hugging Face Spaces requires specific optimizations to avoid uploading massive model files and to leverage serverless GPU acceleration.

Model Management

Instead of uploading models directly, the huggingface_hub library's hf_hub_download function is used to programmatically map local ComfyUI model paths to their corresponding versions on the Hugging Face Hub. This ensures models are downloaded only once when the Space starts.

ZeroGPU Optimization

To enable free inference, the generation function must be decorated with @spaces.GPU. To optimize performance on ZeroGPU and avoid reloading models from disk to GPU on every execution, model declarations should be moved from the decorated function to the global Python context. Pre-loading is then handled via the ComfyUI model_management.load_models_gpu function.

Deployment Steps

  1. Requirements: Consolidate all requirements from custom_nodes folders into a single root requirements.txt file.
  2. Space Configuration: Create a new Space and set the hardware to ZeroGPU (available for PRO subscribers or via a grant request for ComfyUI backends).
  3. File Upload: Upload all ComfyUI folder files except the models folder.
  4. Authentication: For gated models (such as FLUX), add a Hugging Face token as a secret named HF_TOKEN in the Space settings.

Future Automation

Hugging Face intends to automate and streamline the "workflow-to-app" process in early 2025, reducing the need for manual coding and setup.

Sources