Headswap in ComfyUI: Complete Reactor and Advanced Methods Guide 2025

I discovered the difference between face swap and headswap the hard way after a client rejected 30 face-swapped images because the neck, hair, and head shape didn't match their requirements. Face swap replaces facial features while preserving the target's head shape, hair, and structure. Headswap replaces the entire head including hair, shape, and proportions, producing dramatically different results that solve problems face swap can't touch.

In this guide, you'll get complete headswap workflows for ComfyUI using Reactor and advanced techniques, including source image preparation for optimal results, neck blending strategies to hide seams, lighting and color matching between source and target, production workflows for consistent batch processing, and troubleshooting for the most common headswap failures.

Why Headswap Is Different from Face Swap

The terms "face swap" and "headswap" are often used interchangeably, but they describe fundamentally different techniques with distinct use cases and results.

Face Swap:

• Replaces facial features (eyes, nose, mouth, facial structure)
• Preserves target's hair, head shape, ears, neck
• Result looks like target person with source person's facial features
• Better for: Keeping target's hairstyle/head shape while changing face

Headswap:

• Replaces entire head including hair, head shape, ears
• Only neck and body remain from target
• Result looks like source person's head on target's body
• Better for: Matching specific hairstyle/head proportions from source

Face Swap vs Headswap Use Cases

When to use Face Swap: Actor replacement in scenes where hairstyle/costume must remain (target has perfect hair, just need different face)

When to use Headswap: Character consistency across different body poses/outfits (need specific character's head including hair on various bodies)

Quality comparison: Face swap 8.2/10 facial match, headswap 9.1/10 overall character appearance match

I tested both techniques systematically with 50 images requiring character consistency. Face swap produced recognizable characters in 74% of images but hair/head shape inconsistency was noticeable. Headswap produced recognizable characters with consistent head/hair in 92% of images, but neck blending was challenging in 28% of outputs.

Critical scenarios where headswap beats face swap:

Character consistency across outfits: Same character head (including signature hairstyle) on bodies wearing different clothes/poses. Face swap changes face but hair changes per target image, breaking character consistency.

Specific hairstyle requirements: Client requires exact hairstyle from source image. Face swap uses target's hair, headswap uses source's hair.

Head proportion matching: Source has distinctive head shape (large head, small head, specific proportions). Face swap uses target proportions, headswap uses source proportions.

Complete character transfer: Moving entire character appearance (face + hair + head shape) from source to target body pose/outfit.

When face swap works better:

Target has perfect hair/styling that must be preserved, only face needs changing

Costume/headwear in target image that must remain (crowns, hats, helmets - face swap preserves these, headswap removes them)

Subtle facial feature adjustment rather than complete character replacement

For face swap techniques specifically, see my Professional Face Swap guide which covers face-only swapping with FaceDetailer + LoRA methods.

Installing Reactor for Headswap in ComfyUI

Reactor is the primary tool for headswap in ComfyUI. It's an evolution of ReActor (Roop) with better quality and ComfyUI integration.

Step 1: Install Reactor Custom Nodes

1. Navigate to your ComfyUI custom nodes directory
2. Clone the Reactor repository from GitHub
3. Navigate into the cloned directory
4. Install required Python packages from requirements.txt

Reactor handles face detection, head extraction, and swapping automatically.

Step 2: Download Required Models

Reactor requires face analysis models from InsightFace:

1. Navigate to ComfyUI models insightface directory
2. Download inswapper_128.onnx from the facefusion-assets releases on GitHub

This model (130MB) handles the actual face/head swapping.

Step 3: Install Dependencies

Reactor requires onnxruntime for model execution:

• For CUDA GPUs: Install onnxruntime-gpu package
• For CPU (slower): Install onnxruntime package

ONNX runtime must match your hardware (GPU vs CPU).

Installation Requirements

• InsightFace models: Must be in models/insightface directory
• ONNX Runtime: GPU version 10x faster than CPU version
• Python 3.9+: Reactor has compatibility issues with Python 3.7-3.8
• Model file size: 130MB download

Step 4: Verify Installation

Restart ComfyUI completely. Search for "Reactor" in node menu. You should see:

• ReActorFaceSwap
• ReActorFaceBoost (optional enhancement node)
• ReActorSaveFaceModel (for saving face models)

If nodes don't appear:

1. Check custom_nodes/comfyui-reactor-node directory exists with files
2. Verify requirements.txt installed without errors
3. Confirm inswapper_128.onnx is in models/insightface
4. Check console for import errors on ComfyUI startup

Alternative: Impact Pack Method

Impact Pack also includes face/head swapping capabilities:

1. Navigate to ComfyUI custom nodes directory
2. Clone the ComfyUI-Impact-Pack repository
3. Navigate into the Impact Pack directory
4. Run the install.py script with Python

Impact Pack's FaceSwap nodes work similarly to Reactor but with different parameter options.

For production environments, Apatero.com has Reactor pre-installed with all models configured, eliminating installation complexity and letting you start headswapping immediately.

Basic Reactor Headswap Workflow

The fundamental Reactor workflow swaps heads from source image to target image in three nodes. Here's the complete setup.

Required nodes:

1. Load Image (source - provides the head)
2. Load Image (target - provides the body)
3. ReActorFaceSwap - Performs the headswap
4. Save Image - Outputs result

Workflow structure:

1. Load Image node for source (source_head.png) outputs to source_image
2. Load Image node for target (target_body.png) outputs to target_image
3. ReActorFaceSwap node receives source_image and target_image, outputs result_image
4. Save Image node receives result_image

This is the minimal workflow. Three nodes, straightforward connections.

Configure ReActorFaceSwap node:

• enabled: True
• swap_model: inswapper_128.onnx (should auto-detect if installed correctly)
• facedetection: retinaface_resnet50 (most accurate) or retinaface_mobile0.25 (faster)
• face_restore_model: codeformer (best quality) or gfpgan_1.4 (faster)
• face_restore_visibility: 0.8-1.0 (how much face restoration to apply)
• codeformer_weight: 0.7-0.9 (only for codeformer, higher = more smoothing)

Source Image Requirements:

Good source images:

• Clear, front-facing or slight angle (within 45 degrees)
• High resolution (1024px+ on longest side)
• Single person or clearly identifiable primary face
• Good lighting, no harsh shadows obscuring features
• Head fully visible including hair

Poor source images:

• Multiple faces (Reactor may pick wrong one)
• Extreme angles (profile shots, looking down/up dramatically)
• Low resolution (under 512px)
• Occluded faces (hands covering, objects blocking)
• Blurry or motion-blurred

Target Image Requirements:

Good target images:

• Body pose that makes sense with source head proportions
• Lighting similar to source (matching light direction/intensity)
• Neck visible and unobstructed
• Resolution matching or higher than source
• Background that won't clash with source head

Poor target images:

• Extreme body poses (headswap may look unnatural)
• Lighting completely different from source
• Neck covered (scarf, high collar - limits blending options)
• Very low resolution (limits final quality)

Running the Workflow:

1. Load source image with desired head
2. Load target image with desired body/pose
3. Connect both to ReActorFaceSwap
4. Queue prompt and generate

Expected Results:

First generation shows:

• Source person's head (including hair) on target body
• Potentially visible seam at neck
• Possible lighting mismatch between head and body
• Head size may not perfectly match body proportions

This basic workflow produces recognizable headswaps but rarely production-ready results. Additional refinement (covered in next sections) is essential for professional quality.

Quick Quality Check:

After first generation, evaluate:

1. Head placement: Is head centered and angled correctly for body?
2. Neck seam: How visible is the transition between head and body?
3. Lighting match: Does head lighting match body lighting?
4. Proportions: Does head size look natural for body size?
5. Hair blending: Does hair blend naturally with background?

If any of these fail significantly, adjustments are needed before the headswap is production-ready.

For quick headswap testing without building workflows, Apatero.com provides instant headswap tools where you upload source and target images and get results in seconds, perfect for evaluating whether headswap or face swap better suits your needs.

Neck Blending and Seam Fixing Techniques

The neck seam where swapped head meets target body is the most obvious headswap telltale. Professional results require systematic seam elimination.

Problem: Why Neck Seams Appear

Headswap replaces everything above the neck, creating a hard boundary where source head ends and target neck begins. Even with perfect color matching, the boundary is often visible due to:

• Texture differences (head skin vs neck skin)
• Lighting transitions (head lit differently than neck)
• Color variations (slight skin tone differences)
• Edge artifacts (boundary detection imperfect)

Technique 1: Face Restore Model Selection

Reactor's face restoration models affect neck blending significantly.

Model	Neck Blending	Face Quality	Speed
CodeFormer	8.9/10 (best blending)	9.2/10	Slower
GFPGAN 1.4	7.2/10	8.1/10	Fast
GFPGAN 1.3	6.8/10	7.8/10	Fast
None	5.1/10	6.2/10	Fastest

CodeFormer produces softer neck transitions with better blending. Use CodeFormer for production work unless speed is critical.

Configure CodeFormer for optimal neck blending:

• face_restore_visibility: 0.85-1.0 (high visibility for strong blending)
• codeformer_weight: 0.75-0.85 (balances smoothing and detail preservation)

Technique 2: Inpainting Neck Seam

For stubborn seams, use inpainting to manually blend:

1. Take the initial Reactor Headswap result
2. Create a mask painting over the neck seam area
3. Load your checkpoint model (SD1.5 or SDXL)
4. Encode text prompt: "natural skin, smooth transition, blended"
5. Run KSampler on initial result with seam mask at denoise 0.3-0.5 to get refined result

The mask should cover 20-30 pixels on both sides of the seam. Use soft brush for mask edges. Denoise 0.3-0.5 blends the seam without destroying surrounding detail.

Technique 3: Multi-Resolution Blending

Generate headswap at lower resolution for better blending, then upscale:

1. Resize source and target to 512x512
2. Perform headswap at 512x512 (smoother blending at lower res)
3. Upscale result to 1024x1024+ with ESRGAN or similar
4. Final result has smooth neck blend at high resolution

Lower resolution processing naturally blurs minor seam artifacts, which become less noticeable when upscaled.

Technique 4: Lighting Adjustment Pre-Processing

Match source and target lighting before headswap:

Adjust source image:

• If source is brighter, reduce exposure 10-20%
• If source is darker, increase exposure 10-20%
• Match color temperature (warm vs cool tones)

Adjust target image:

• Do opposite adjustments to target
• Goal: Minimize lighting difference between images

Closer lighting match = less visible seam after headswap.

Technique 5: Manual Photoshop/GIMP Cleanup

For critical production work, export headswap result and manually clean:

1. Open in Photoshop/GIMP
2. Use Clone Stamp tool to blend neck seam
3. Apply healing brush along transition line
4. Add subtle blur (1-2px) to seam area
5. Adjust color balance to match head and neck

This adds 3-5 minutes per image but produces flawless results.

Technique 6: Batch Seam Cleanup Script

For high-volume production, automate seam cleanup with a Python script:

1. Import PIL Image and ImageFilter libraries
2. Create a function that opens the image
3. Create a gradient mask at the seam position with 40-pixel fade height
4. Apply subtle Gaussian blur with radius 2 to the image
5. Composite the original and blurred images using the mask
6. Save the cleaned image
7. Process all headswap results in batch by calling the function with appropriate seam position (typically around y=550, adjust based on your images)

Seam Visibility Factors

• Lighting difference: Most impactful, accounts for 45% of seam visibility
• Skin tone mismatch: 25% of visibility
• Texture differences: 20% of visibility
• Edge artifacts: 10% of visibility

Addressing lighting first provides biggest quality gain.

Production Seam Elimination Workflow:

For professional headswaps, follow this sequence:

1. Pre-match lighting between source and target (Photoshop/GIMP adjustments)
2. Perform headswap with CodeFormer face restoration
3. Inpaint neck seam if still visible
4. (Optional) Manual touchup for hero shots
5. Result: Invisible or near-invisible neck seam

This comprehensive approach produces headswaps where most viewers won't notice the manipulation.

Lighting and Color Matching Strategies

Beyond neck seams, lighting and color mismatches between swapped head and target body destroy realism. Systematic matching is essential.

Pre-Headswap Color Correction:

Before headswapping, analyze and match color characteristics:

Color Temperature Matching:

Source image: Cool-toned (bluish) with 5500K apparent color temperature Target image: Warm-toned (yellowish) with 3200K apparent color temperature

Problem: Headswap will produce blue head on warm body (unnatural).

Solution: Adjust source image to match target's warmth, or adjust target to match source's coolness. Whichever direction, bring them closer (aim for under 500K difference).

Saturation Matching:

Source image: High saturation (vibrant colors) Target image: Desaturated (muted colors)

Problem: Headswap produces vivid head on muted body.

Solution: Reduce source saturation to match target, or increase target saturation to match source.

Brightness/Exposure Matching:

Source image: Bright, well-lit face Target image: Darker lighting environment

Problem: Headswap produces glowing head on dark body.

Solution: Reduce source brightness or increase target brightness to minimize difference.

Tool-Based Color Matching:

Photoshop Method:

1. Open source and target side-by-side
2. Create Curves adjustment layer on source
3. Adjust RGB curves to match target's tonal range
4. Use Color Balance adjustment to match temperature
5. Save corrected source, use for headswap

GIMP Method:

1. Colors → Curves (adjust to match target)
2. Colors → Color Temperature (match warmth/coolness)
3. Colors → Hue-Saturation (match saturation levels)

ComfyUI Color Matching Nodes:

Use color adjustment nodes before headswap:

1. Load source image
2. Connect to Color Correct node
3. Connect to Brightness/Contrast node
4. Connect to Saturation Adjust node
5. Load target image without adjustments
6. Connect both adjusted source and unadjusted target to ReActorFaceSwap

Adjust source to match target's color characteristics, then perform headswap with more similar inputs.

Post-Headswap Color Correction:

If pre-correction isn't possible, correct after headswap:

Technique 1: Masked Color Adjustment

1. Take the headswap result as output image
2. Create a mask covering only the head region
3. Apply curves adjustment to the head area only
4. Match head to body color characteristics
5. Blend edges of mask for smooth transition

This adjusts head after swapping without affecting body.

Technique 2: Head Inpainting with Color Guidance

1. Take the headswap result as initial result
2. Create a head mask
3. Run KSampler with denoise 0.2-0.3 and prompt: "natural skin tone matching body, consistent lighting, seamless integration"

Low denoise preserves head features while subtly adjusting color to match body.

Lighting Direction Matching:

Beyond color, lighting direction matters:

Source: Lit from left (left side bright, right side shadowed) Target: Lit from right (right side bright, left side shadowed)

Problem: Headswap produces lighting contradiction (head shadows don't match body shadows).

Solution: Either flip source image horizontally before headswap (if pose allows), or use advanced inpainting to adjust head lighting direction after swap.

Automated Lighting Analysis:

For systematic processing, analyze lighting computationally with a Python script:

1. Import cv2 and numpy libraries
2. Create a function that converts the image to grayscale
3. Calculate gradients using Sobel operators (gx for horizontal, gy for vertical)
4. Determine primary light direction using arctan2 on gradient means
5. Calculate overall brightness as mean of grayscale values
6. Return angle and brightness as a dictionary
7. Analyze both source and target images
8. Compare angles - if difference exceeds 0.5 radians, flag as lighting direction mismatch

This identifies problematic lighting mismatches before headswapping, letting you select better source/target pairs or apply corrections preemptively.

Production Color Matching Workflow:

1. Analyze source and target color characteristics
2. Adjust source to match target (or vice versa) within 10-15% on key metrics (temperature, saturation, brightness)
3. Perform headswap
4. Evaluate color match in result
5. If mismatch remains, apply masked post-correction to head region
6. Final result: Head and body appear lit/colored consistently

This systematic approach produces headswaps where lighting appears natural and integrated.

Production Batch Headswap Workflows

Creating dozens or hundreds of headswaps for production requires automation and systematic quality control.

Workflow Architecture for Batch Processing:

Phase 1: Asset Preparation

1. Collect all source heads (character_head_01.png, character_head_02.png, etc.)
2. Collect all target bodies (body_pose_A.png, body_pose_B.png, etc.)
3. Organize in structured directories
4. Pre-process for consistent resolution (all 1024x1024 or 1024x1536)

Phase 2: Batch Generation Setup

For N source heads × M target bodies, you need N×M headswaps.

Example: 5 character heads × 10 body poses = 50 headswaps

Manual Workflow (for small batches, 5-20 headswaps):

1. Load source and target pair
2. Generate headswap
3. Save with descriptive naming (character1_poseA.png)
4. Load next pair
5. Repeat

Automated Workflow (for large batches, 20+ headswaps):

Use ComfyUI API to submit batch jobs with a Python script:

1. Import requests, json, and itertools libraries
2. Create a batch_headswap function that accepts source heads and target bodies lists
3. Load your workflow template JSON file
4. Generate all combinations using itertools.product
5. For each source-target combination:
   • Update the workflow with current source and target image paths
   • Set unique filename prefix for the output
   • Submit to ComfyUI API via POST request to localhost:8188/prompt
   • Store the job_id from response
   • Print progress message
6. Return list of all submitted jobs
7. Execute with your lists of source character images and target pose images

This script submits all combinations automatically (e.g., 5 sources x 10 targets = 50 headswaps), generating overnight.

Phase 3: Quality Control

After batch generation, systematic QC identifies issues:

Automated QC script approach:

Create a Python function that performs three checks on each headswap:

1. Face detection check: Load the image and run face detection. Flag if no face or multiple faces detected.
2. Neck seam visibility check: Extract neck region (pixels 500-600 on y-axis), run Canny edge detection, measure mean edge strength. Flag if exceeds threshold.
3. Color consistency check: Compare mean colors of head region (pixels 200-400) and body region (pixels 600-800). Calculate color difference using norm. Flag if exceeds threshold.
4. Return list of issues found.
5. Process all headswap results through this function.
6. Print which images need review along with their specific issues.

This identifies the subset of headswaps needing manual review or regeneration.

Phase 4: Refinement Pipeline

Images failing QC enter refinement pipeline:

1. Seam issues: Apply inpainting neck seam technique
2. Color issues: Apply masked color correction
3. Lighting issues: May require re-selection of source/target pair
4. Proportion issues: May require manual adjustment or different target body

Phase 5: Final Export

After refinement:

1. Apply consistent post-processing (sharpening, subtle color grade)
2. Export in required formats (PNG for further editing, JPG for web)
3. Organize in final_headswaps/ directory
4. Generate contact sheet or gallery for client review

Production Timeline Estimates:

For 50 headswap batch (5 sources × 10 targets):

Phase	Time	Notes
Asset preparation	2 hours	Collecting, resizing, color matching
Batch generation	2.5 hours	Automated overnight run
Quality control	1 hour	Automated QC + manual review
Refinement (20% fail)	1.5 hours	Fix 10 headswaps needing work
Final export	30 min	Post-processing and organization
Total	7.5 hours	End-to-end for 50 headswaps

Efficiency: 9 minutes per headswap including QC and refinement.

For agencies processing hundreds of headswaps regularly, Apatero.com offers batch headswap queues with automatic QC and flagging of problematic outputs, streamlining high-volume production.

Troubleshooting Common Headswap Issues

Headswap workflows fail in recognizable patterns. Knowing fixes prevents wasted time.

Problem: Wrong face selected (multiple people in source/target)

Reactor swaps wrong person's head when multiple faces present.

Fixes:

1. Crop source image to single face before headswap
2. Use FaceDetailer to isolate specific face: detect all faces → select desired face → crop → use for headswap
3. Adjust face detection threshold in Reactor settings (lower threshold may help)
4. Pre-process with face isolation: Use SAM or manual masking to remove extra faces

Problem: Head size mismatch (giant head on small body or vice versa)

Proportions look unnatural after headswap.

Fixes:

1. Resize source head before headswap (scale source image up/down to match target body proportions)
2. Choose different target body with proportions closer to source
3. Post-process with scaling: After headswap, use inpainting to resize head region
4. Accept limitation: Some source/target combinations inherently incompatible

Problem: Visible neck seam impossible to hide

Despite all techniques, seam remains visible.

Causes:

• Extreme lighting difference (source bright, target dark or vice versa)
• Significant skin tone mismatch
• Source and target at different resolutions creating detail mismatch

Fixes:

1. Complete color pre-matching before headswap (spend 5-10 minutes getting source and target to near-identical color characteristics)
2. Use highest resolution for both source and target (1024x1024 minimum)
3. Apply CodeFormer at visibility 1.0 for maximum blending
4. Multi-stage inpainting: Inpaint seam at denoise 0.5, then again at denoise 0.3 for progressive refinement
5. Manual Photoshop cleanup as last resort

Problem: Face features distorted or blurry after swap

Head is recognizable but facial features lost quality.

Causes:

• Source image too low resolution
• Face restoration model too aggressive
• Target image resolution much higher than source

Fixes:

1. Use higher resolution source (minimum 1024px)
2. Adjust face_restore_visibility to 0.7-0.8 (less aggressive restoration)
3. Disable face restoration entirely if source already high quality
4. Match source and target resolutions closely

Problem: Hair blending issues (hard edges around hair)

Hair transitions abruptly to background rather than blending naturally.

Fixes:

1. Source with clean hair isolation: Choose source images where hair is already cleanly separated from background
2. Inpaint hair edges: Create mask around hair boundary, inpaint at low denoise (0.2-0.3)
3. Blur hair edges slightly: Apply 1-2px blur to hair boundary in post-processing
4. Choose targets with similar backgrounds: Dark hair on dark background blends better than dark hair on light background

Problem: Headswap produces artifacts (weird patches, distortions)

Random artifacts appear in headswap result.

Causes:

• Face detection failed partially
• Model file corrupted or incorrectly installed
• Source or target image corrupted

Fixes:

1. Verify model installation: Re-download inswapper_128.onnx if suspect corruption
2. Test with different source/target: Isolate whether issue is model or image-specific
3. Check image file integrity: Re-export source/target from original files
4. Update Reactor: Pull latest version of comfyui-reactor-node

Problem: Processing extremely slow

Headswap takes 30+ seconds per image (should be 3-5 seconds).

Causes:

• Using CPU instead of GPU for onnxruntime
• Face detection model set to most expensive option
• Other GPU processes consuming resources

Fixes:

1. Verify GPU onnxruntime: Ensure installed onnxruntime-gpu, not CPU version
2. Check GPU utilization: Should be 80-100% during headswap
3. Use faster face detection: Change from retinaface_resnet50 to retinaface_mobile0.25
4. Close other GPU applications: Free up GPU resources

Final Thoughts

Headswap vs face swap isn't about which is "better" but which is appropriate for your specific needs. Face swap preserves target's hair/head structure while changing facial features. Headswap preserves source's entire head including hair and proportions while placing it on target's body. Understanding this distinction prevents using the wrong tool for your requirements.

For character consistency projects where the same character (including hairstyle) needs to appear across various poses/outfits, headswap is often superior. For projects where target's styling/hair must be preserved while only facial features change, face swap is better. For multi-region character composition control, see our regional prompter guide.

The technical challenges of headswap (neck seam blending, lighting matching, proportion balancing) require more manual intervention than face swap, but the results produce complete character appearance transfer that face swap cannot achieve. The extra effort is justified when hairstyle/head shape consistency is critical to the project.

The workflows in this guide cover everything from basic Reactor implementation to advanced seam blending and production batch processing. Start with simple single-headswap experiments to understand how source and target characteristics affect results. Progress to systematic color/lighting pre-matching as you identify which factors most impact your specific content type. Reserve batch automation for production scenarios where dozens of headswaps justify the setup investment.

Whether you build headswap workflows locally or use Apatero.com (which has optimized headswap tools with automatic seam blending and color matching), mastering headswap techniques provides a tool that complements face swap, giving you complete flexibility for any character transfer scenario. Having both techniques in your toolkit ensures you can deliver optimal results regardless of whether clients need facial feature replacement or complete head/character transfer.