Registry / ai-ml / controlnet-aux

controlnet-aux

JSON →
library0.0.10pypypiunverified

ControlNet Auxiliary Models (controlnet-aux) provides a PyPI installable package of lllyasviel's ControlNet Annotators. It offers various preprocessors (e.g., Canny, OpenPose, Midas) for generating hint images like edges, depth maps, and poses, which are used to guide image generation with ControlNet models. The library is currently at version 0.0.10, released on May 8, 2025, with an irregular release cadence primarily driven by upstream ControlNet updates.

pip install -U controlnet-aux
INSTALL
IMPORT
SIG · CONTROLNET-AUX
C
controlnet-aux
ai-mlpythonv0.0.10
Install
87.6s avg
Import
15015ms
Disk
8653MB
Pass rate
2/ 10
Env Coverage2 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.0.10 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✕ build_error
✓ 91.58s
py 3.11
✕ build_error
✓ 83.71s
py 3.12
✕ build_error
4/8 runs
py 3.13
✕ build_error
4/8 runs
py 3.9
✕ build_error
✕ timeout
8653MB installed
● package 8653MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Processor
from controlnet_aux.processor import Processor
Recommended unified interface for most annotators
HEDdetector
from controlnet_aux import HEDdetector
For direct import of individual detectors/annotators
OpenposeDetector
from controlnet_aux import OpenposeDetector
For direct import of individual detectors/annotators

This quickstart demonstrates how to use the unified `Processor` class to load and apply a ControlNet annotator (e.g., OpenPose) to an input image. The `Processor` dynamically loads the necessary models based on the `processor_id` you specify.

import requests from PIL import Image from io import BytesIO from controlnet_aux.processor import Processor # Load an image from a URL url = "https://huggingface.co/lllyasviel/sd-controlnet-openpose/resolve/main/images/pose.png" response = requests.get(url) img = Image.open(BytesIO(response.content)).convert("RGB") # Instantiate the processor for a specific ControlNet annotator (e.g., 'openpose') # Common processor_ids include: 'canny', 'depth_leres', 'openpose', 'scribble_hed', 'lineart_realistic', 'dwpose' processor_id = 'openpose' processor = Processor(processor_id) # Process the image processed_image = processor(img, to_pil=True) # Display or save the processed image # processed_image.show() # Uncomment to display print(f"Image processed successfully using {processor_id}. Output image size: {processed_image.size}")
Debug
Known issues
gotchaDWPose can be significantly slower when running on CPU. For optimal performance, especially with DWPose or AnimalPose, consider using TorchScript checkpoints or ONNXRuntime with GPU acceleration.
fix
Install `easy-dwpose` (which uses ONNX models) and ensure your environment is configured for ONNXRuntime or PyTorch with GPU (e.g., CUDA) for faster inference. Refer to documentation for specific setup instructions.
affects: All versions
gotchaWhen processing images for ControlNet, it is recommended that the input image resolution (or target detection resolution) be a multiple of 64 to maintain the aspect ratio and ensure optimal performance and output quality.
fix
Resize your input images or adjust `detect_resolution` and `image_resolution` parameters to be multiples of 64. PIL's `resize` method can be used for this.
affects: All versions
breakingInstalling `controlnet-aux` alongside older `comfyui_controlnet_preprocessors` or similar custom nodes in ComfyUI can lead to import conflicts or unexpected behavior due to overlapping functionalities and potentially outdated dependencies.
fix
If using ComfyUI, ensure that `comfyui_controlnet_preprocessors` is completely removed before installing `controlnet-aux` based custom nodes. Always follow the installation instructions specific to your ComfyUI custom node setup.
affects: Versions 0.0.7+
Upgrade
Version history
0.0.10latest on PyPI · released May 8, 2025
Audit
Dependencies
einopsrequiredRequired for array manipulation
filelockrequiredFor resource locking
huggingface_hubrequiredFor model downloading and management
importlib_metadatarequiredFor package metadata
numpyrequiredFundamental package for numerical computation
opencv-python-headlessrequiredCore computer vision functionalities
pillowrequiredImage processing library
scikit-imagerequiredImage processing algorithms
scipyrequiredScientific computing tools
timmrequiredPyTorch Image Models, used by some annotators
torchrequiredMain deep learning framework
torchvisionrequiredVision datasets, models and transforms for PyTorch
easy-dwposeoptionalLightweight DWPose implementation without MMDetection/MMCV/MMPose; highly recommended for DWPose.
Agent activity
39 hits · last 30 days
node
34
OpenAI (training)
1
Resources
controlnet-aux — pip install controlnet-aux · libregistry