From 1a56b1dcea08db91f1f99e0e747ebe1cd4efbcb6 Mon Sep 17 00:00:00 2001 From: John-Caldwell <98851904+John-Caldwell@users.noreply.github.com> Date: Mon, 10 Nov 2025 17:20:54 -0600 Subject: [PATCH] Add comprehensive PR description for preinstall enhancements --- PR_DESCRIPTION.md | 194 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 194 insertions(+) create mode 100644 PR_DESCRIPTION.md diff --git a/PR_DESCRIPTION.md b/PR_DESCRIPTION.md new file mode 100644 index 000000000..40e9388a1 --- /dev/null +++ b/PR_DESCRIPTION.md @@ -0,0 +1,194 @@ +# Enhanced run_comfyui.bat with Automated Dependency Checking and CUDA PyTorch Installation + +## Author's Note + +**Important**: I am not a professional coder and have relied heavily on Cursor AI for the development of this script. While I have done my best to ensure its functionality and safety, I kindly request a thorough review by experienced developers before merging. Please pay special attention to: +- Batch file logic and error handling +- Python command-line invocations +- Virtual environment detection logic +- Dependency checking implementation +- User interaction flow + +## Overview + +This PR enhances the `run_comfyui.bat` startup script for Windows users, significantly improving the user experience by automatically checking dependencies, detecting virtual environments, and offering intelligent installation options. The script now provides a polished, user-friendly interface with clear error messages and troubleshooting guidance. + +## Key Features + +### 1. **Automated Dependency Checking** +- Checks all critical Python dependencies before launching ComfyUI +- Separates critical vs. optional dependencies +- Provides clear prompts for missing packages +- Offers installation options: Install All, Critical Only, or Cancel + +### 2. **CUDA PyTorch Auto-Installation** +- Automatically detects CPU-only PyTorch installations +- Offers to automatically uninstall CPU version and install CUDA-enabled version +- Shows progress bars during installation (`--progress-bar on`) +- Verifies installation before proceeding +- Provides clear warnings about NVIDIA GPU requirements + +### 3. **Virtual Environment Awareness** +- Detects if running in a virtual environment +- Provides appropriate warnings about installation impacts +- Offers guidance on creating virtual environments for safer package management + +### 4. **Enhanced User Experience** +- UTF-8 encoding support for proper Unicode character display +- ASCII art banner with "Comfy" text +- Progress bars for all pip installations +- User-friendly error messages with actionable troubleshooting steps +- Clear, informative prompts throughout the installation process + +### 5. **Comprehensive Error Handling** +- Detailed error messages for common issues: + - Python not found + - Installation failures + - CUDA out of memory errors + - Module not found errors +- Provides specific troubleshooting steps for each error type + +## Files Changed + +- **`run_comfyui.bat`** (408 lines, +347 insertions, -61 deletions) + - Enhanced startup script with all new features + - UTF-8 encoding support + - Comprehensive dependency checking + - CUDA PyTorch detection and auto-installation + - Virtual environment detection + - Progress bars for installations + - User-friendly error messages + +- **`create_shortcut.ps1`** (1 line addition) + - PowerShell script for creating desktop shortcuts + - Helper utility for easier access + +## Screenshots + +### ASCII Art Banner +The script displays a polished ASCII art banner with "Comfy" text: +``` +╔═══════════════════════════════════════════════════════════╗ +║ ║ +║ ██████╗ ██████╗ ███╗ ███╗███████╗██╗ ██╗ ║ +║ ██╔════╝██╔═══██╗████╗ ████║██╔════╝╚██╗ ██╔╝ ║ +║ ██║ ██║ ██║██╔████╔██║█████╗ ╚████╔╝ ║ +║ ██║ ██║ ██║██║╚██╔╝██║██╔══╝ ╚██╔╝ ║ +║ ╚██████╗╚██████╔╝██║ ╚═╝ ██║██║ ██║ ║ +║ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ║ +║ ║ +║ The most powerful open source node-based ║ +║ application for generative AI ║ +║ ║ +╚═══════════════════════════════════════════════════════════╝ +``` + +### Key User Interactions + +**Dependency Checking Prompt:** +``` +╔═══════════════════════════════════════════════════════════╗ +║ Missing Required Packages ║ +╚═══════════════════════════════════════════════════════════╝ + +▓ ComfyUI needs some additional software to run. + The following critical packages are missing: + yaml, torch, numpy + +▓ [Heads Up] You're using your main Python installation. + Installing packages here might affect other programs that use Python. + +▓ Installation Options: + [I] Install all missing packages (recommended) + [C] Install only critical packages + [N] Cancel and exit +``` + +**CUDA PyTorch Detection:** +``` +╔═══════════════════════════════════════════════════════════╗ +║ CPU-Only PyTorch Detected - CUDA Version Required ║ +╚═══════════════════════════════════════════════════════════╝ + +▓ Your PyTorch installation doesn't support GPU acceleration. + ComfyUI requires CUDA-enabled PyTorch to run properly. + +▓ We can automatically install the CUDA-enabled version for you. + This will: + 1. Remove the current CPU-only version + 2. Install the CUDA-enabled version (this will take several minutes) + 3. Continue to launch ComfyUI automatically + +Would you like to install CUDA-enabled PyTorch now? (Y/N): +``` + +## Testing Recommendations + +To thoroughly test this PR, please verify the following scenarios: + +1. **Clean Environment**: Run the script in an environment with no Python or ComfyUI dependencies installed +2. **Missing Critical Dependencies**: Manually uninstall one or more critical dependencies (e.g., `pyyaml`) and verify the script correctly identifies them +3. **Missing Optional Dependencies**: Uninstall an optional dependency and verify the script offers to install it or skip +4. **CPU-Only PyTorch**: Install a CPU-only version of PyTorch and verify the script detects it and offers to install the CUDA version +5. **CUDA-Enabled PyTorch**: Ensure a CUDA-enabled PyTorch is installed and verify the script proceeds directly to launching ComfyUI +6. **Virtual Environment**: Test running the script within an activated virtual environment +7. **System Python**: Test running the script with system Python (not in a virtual environment) +8. **Error Handling**: Verify that all error messages are clear, informative, and provide helpful troubleshooting steps +9. **Progress Bars**: Verify that progress bars display correctly during pip installations +10. **ASCII Art**: Confirm the ASCII art banner renders correctly in a standard Windows command prompt + +## Technical Details + +### UTF-8 Encoding +- Uses `chcp 65001` to enable UTF-8 encoding for proper Unicode character display +- Ensures ASCII art and box-drawing characters render correctly + +### Dependency Checking +- Uses `importlib.util.find_spec()` to check for module availability +- Separates critical dependencies (required for ComfyUI to run) from optional dependencies +- Provides user with clear installation options + +### CUDA PyTorch Detection +- Checks PyTorch version string for "+cpu" indicator +- Verifies CUDA availability using `torch.cuda.is_available()` +- Automatically updates CUDA availability variables after installation +- Continues to launch ComfyUI after successful installation + +### Progress Bars +- Uses `--progress-bar on` flag for all pip installations +- Provides visual feedback during long installations (especially PyTorch) + +## Backward Compatibility + +- ✅ All changes are backward compatible +- ✅ No breaking changes to existing functionality +- ✅ Works with both system Python and virtual environments +- ✅ Existing users can continue using the script as before + +## Benefits + +1. **Improved User Experience**: Users get clear guidance on what's missing and how to fix it +2. **Reduced Support Burden**: Common issues are caught and resolved automatically +3. **Better Error Messages**: Users understand what went wrong and how to fix it +4. **Professional Appearance**: Polished interface with ASCII art and clear formatting +5. **GPU Support**: Automatically ensures users have CUDA-enabled PyTorch for optimal performance + +## Additional Notes + +- The script maintains all original functionality while adding new features +- All user prompts are optional - users can cancel at any time +- Installation commands use `python -m pip` for consistency +- Error handling provides actionable troubleshooting steps +- The script is designed to be safe and non-destructive + +## Request for Review + +Given my limited coding experience, I would greatly appreciate: +- Code review focusing on batch file best practices +- Verification of Python command invocations +- Testing in various Windows environments +- Feedback on error handling and user prompts +- Suggestions for improvements + +Thank you for your time and consideration! +