jonstreeter-ComfyUI-Reference-Based-Video-Colorization/AUTO_INSTALLER_README.md

Auto-Installer Documentation

Silent dependency installer for modern video colorization components

---

Overview

The auto-installer automatically detects and installs missing Python packages when users select modern components (DINOv2, CLIP, color-matcher, etc.) in the ComfyUI nodes.

Key Features:

• ✅ Silent installation with progress logging
• ✅ Smart caching to avoid repeated attempts
• ✅ Graceful failure handling
• ✅ Can run standalone or integrated
• ✅ No user interaction required

---

Architecture

Module: auto_installer.py

Core Functions:

1. check_package_installed(package_name)

   • Checks if a package is importable
   • Returns True/False

2. install_package(package_spec, display_name)

   • Installs via pip subprocess
   • Silent installation (stdout suppressed)
   • Caches result to avoid retry
   • Returns True on success

3. Component-Specific Installers:

   • ensure_timm() - For DINOv2 encoders
   • ensure_clip() - For CLIP encoder
   • ensure_color_matcher() - For color-matcher post-processing
   • ensure_opencv_contrib() - For WLS/Guided filters

4. Smart Installers:

   • ensure_dependencies_for_encoder(encoder_type) - Auto-detects encoder needs
   • ensure_dependencies_for_post_processor(processor_type) - Auto-detects processor needs

5. Batch Installer:

   • install_all_modern_components() - Installs everything at once

---

Integration with Nodes

Image Node Integration

# In colorize_image() method
if feature_encoder != "vgg19":
    # Auto-install dependencies
    from .auto_installer import ensure_dependencies_for_encoder
    deps_ok = ensure_dependencies_for_encoder(feature_encoder)

    if deps_ok:
        # Load modern encoder
        encoder_net = get_feature_encoder(feature_encoder, device='cuda')
    else:
        # Fall back to VGG19
        encoder_net = VGG_NET

Post-Processor Integration

# In colorize_image() method
if post_processor != "none":
    # Auto-install dependencies
    from .auto_installer import ensure_dependencies_for_post_processor
    deps_ok = ensure_dependencies_for_post_processor(post_processor)

    if deps_ok:
        # Create post-processor
        proc = get_post_processor(post_processor, **kwargs)

---

Installation Flow

User Perspective:

1. User selects dinov2_vitb in ComfyUI node
2. Runs workflow
3. Console shows:

   [AutoInstall] timm not found (required for DINOv2)
   [AutoInstall] Installing timm (DINOv2 support)...
   [AutoInstall] ✓ timm installed successfully
   [DeepExColorImageNode] ✓ Using feature encoder: dinov2_vitb
   

4. Node loads DINOv2 and continues normally
5. Next run: Already installed, no messages

Developer Perspective:

# Call chain:
ensure_dependencies_for_encoder('dinov2_vitb')
  └─> ensure_timm()
      └─> check_package_installed('timm')  # Returns False
      └─> install_package('timm>=0.9.0', 'timm (DINOv2 support)')
          └─> subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'timm>=0.9.0'])
          └─> Cache result in _INSTALLATION_CACHE
          └─> Return True

---

Dependency Mapping

Encoders:

Encoder Type	Dependencies	Auto-Install Function
vgg19	None	N/A
dinov2_vits	timm>=0.9.0	ensure_timm()
dinov2_vitb	timm>=0.9.0	ensure_timm()
dinov2_vitl	timm>=0.9.0	ensure_timm()
clip_vitb	clip @ git+https://...	ensure_clip()

Post-Processors:

Processor Type	Dependencies	Auto-Install Function
none	None	N/A
bilateral	opencv-python	Already required
wls	opencv-contrib-python>=4.7.0	ensure_opencv_contrib()
guided	opencv-contrib-python>=4.7.0	ensure_opencv_contrib()
color_matcher	color-matcher>=0.3.0	ensure_color_matcher()

---

Caching Mechanism

Problem: Don't want to retry installation every time if it failed once

Solution: Global cache dictionary

_INSTALLATION_CACHE = {}

def install_package(package_spec, display_name):
    # Check cache first
    if package_spec in _INSTALLATION_CACHE:
        return _INSTALLATION_CACHE[package_spec]

    # Try installation
    success = do_pip_install(package_spec)

    # Cache result
    _INSTALLATION_CACHE[package_spec] = success
    return success

Cache lifetime: Process lifetime (cleared on ComfyUI restart)

---

Error Handling

Graceful Failure:

try:
    # Auto-install
    deps_ok = ensure_dependencies_for_encoder(feature_encoder)

    if deps_ok:
        encoder_net = get_feature_encoder(feature_encoder)
    else:
        raise ImportError(f"Dependencies could not be installed")

except Exception as e:
    print(f"Warning: Could not load {feature_encoder}: {e}")
    print("Falling back to VGG19")
    encoder_net = VGG_NET

Node never crashes - Always falls back to VGG19 or no post-processing

---

Standalone Usage

Install Everything:

cd ComfyUI/custom_nodes/ComfyUI-Reference-Based-Video-Colorization
python auto_installer.py

Output:

[AutoInstall] Installing all modern components...
[AutoInstall] This may take a few minutes on first run...
[AutoInstall] Installing timm (DINOv2 support)...
[AutoInstall] ✓ timm installed successfully
[AutoInstall] Installing CLIP...
[AutoInstall] ✓ CLIP installed successfully
[AutoInstall] Installing color-matcher...
[AutoInstall] ✓ color-matcher installed successfully
[AutoInstall] Installing opencv-contrib-python...
[AutoInstall] ✓ opencv-contrib-python installed successfully

[AutoInstall] Installation Summary:
[AutoInstall]   ✓ timm
[AutoInstall]   ✓ clip
[AutoInstall]   ✓ color_matcher
[AutoInstall]   ✓ opencv_contrib
[AutoInstall] ✓ All components installed successfully!

Programmatic Usage:

from auto_installer import (
    ensure_timm,
    ensure_clip,
    ensure_color_matcher,
    install_all_modern_components
)

# Install specific component
if ensure_timm():
    print("timm is ready!")

# Install everything
results = install_all_modern_components()

---

Console Output Examples

First-Time DINOv2 Usage:

[AutoInstall] timm not found (required for DINOv2)
[AutoInstall] Installing timm (DINOv2 support)...
[AutoInstall] ✓ timm installed successfully
[DeepExColorImageNode] ✓ Using feature encoder: dinov2_vitb

First-Time CLIP Usage:

[AutoInstall] CLIP not found (required for text-guided colorization)
[AutoInstall] Installing CLIP...
[AutoInstall] ✓ CLIP installed successfully
[DeepExColorImageNode] ✓ Using feature encoder: clip_vitb
[DeepExColorImageNode] ✓ Text guidance: 'warm sunset colors' (weight=0.3)

First-Time color-matcher Usage:

[AutoInstall] color-matcher not found (required for color matching post-processing)
[AutoInstall] Installing color-matcher...
[AutoInstall] ✓ color-matcher installed successfully
[DeepExColorImageNode] ✓ Post-processing applied: color_matcher

Installation Failure:

[AutoInstall] timm not found (required for DINOv2)
[AutoInstall] Installing timm (DINOv2 support)...
[AutoInstall] ✗ Failed to install timm: <error details>
[DeepExColorImageNode] Warning: Could not load dinov2_vitb: Dependencies could not be installed
[DeepExColorImageNode] Falling back to VGG19

---

Platform Considerations

Windows:

• Works out of the box
• May need to run ComfyUI as administrator if permissions issue

Linux/Mac:

• Usually works without sudo
• If permission denied: User needs to manually run with sudo or --user flag

Virtual Environments:

• Auto-installs into current Python environment
• Uses sys.executable to ensure correct pip

---

Security Considerations

Safe:

• ✅ Only installs from PyPI or official GitHub repos
• ✅ Uses specific version constraints
• ✅ No arbitrary code execution
• ✅ Suppresses stdout but preserves stderr for debugging

Limitations:

• ⚠️ Installs packages without user confirmation
• ⚠️ May conflict with existing installations
• ⚠️ Requires internet connection

Mitigation:

• Users can disable by manually setting feature_encoder: vgg19
• Clear console output shows what's being installed
• Graceful failure doesn't break workflow

---

Testing

Test Auto-Installer Standalone:

# Uninstall packages first
pip uninstall -y timm clip color-matcher

# Run auto-installer
python auto_installer.py

# Verify installation
python -c "import timm; import clip; from color_matcher import ColorMatcher; print('✓ All installed')"

Test Node Integration:

1. Uninstall timm: pip uninstall -y timm
2. In ComfyUI, set feature_encoder: dinov2_vitb
3. Run workflow
4. Check console for auto-install messages
5. Verify node uses DINOv2 successfully

---

Future Enhancements

Potential improvements:

1. User confirmation prompt:

   print(f"Install {package}? [Y/n]")
   if input().lower() == 'y':
       install_package(package)
   

2. Download progress bar:

   # Instead of suppressing stdout
   subprocess.check_call([...], stdout=None)
   

3. Offline mode:

   def install_package(..., allow_network=True):
       if not allow_network:
           print("Offline mode - skipping installation")
           return False
   

4. Version checking:

   def check_package_version(package, min_version):
       # Check if installed version meets requirement
   

---

Troubleshooting

Auto-installer not running:

Check:

• Is auto_installer.py in the correct directory?
• Are imports working? from .auto_installer import ...

Installation fails:

Common causes:

• No internet connection
• Firewall blocking pip
• Insufficient permissions
• Conflicting package versions

Solution:

• Check console for specific error
• Try manual install: pip install <package>
• Check pip works: pip --version

Packages install but don't import:

Possible cause:

• Multiple Python environments
• ComfyUI using different Python than pip

Solution:

• Use sys.executable (auto-installer already does this)
• Verify with: which python and which pip

---

API Reference

check_package_installed(package_name: str) -> bool

Check if package can be imported.

Args:

• package_name: Module name to import (e.g., 'timm', 'clip')

Returns:

• True if importable, False otherwise

---

install_package(package_spec: str, display_name: Optional[str] = None) -> bool

Install a package via pip.

Args:

• package_spec: Pip package specification (e.g., 'timm>=0.9.0')
• display_name: Human-readable name for logging

Returns:

• True if installation successful, False otherwise

---

ensure_dependencies_for_encoder(encoder_type: str) -> bool

Ensure all dependencies for encoder are installed.

Args:

• encoder_type: Encoder name ('dinov2_vitb', 'clip_vitb', etc.)

Returns:

• True if dependencies available, False otherwise

---

ensure_dependencies_for_post_processor(processor_type: str) -> bool

Ensure all dependencies for post-processor are installed.

Args:

• processor_type: Processor name ('color_matcher', 'wls', etc.)

Returns:

• True if dependencies available, False otherwise

---

install_all_modern_components() -> dict

Install all modern components at once.

Returns:

• Dictionary with installation status: {'timm': True, 'clip': True, ...}

---

Auto-installer makes modern AI models accessible with zero configuration! 🚀