MuseTalk Troubleshooting Guide: Find Your Error and Fix It

If MuseTalk is not installing, starting, detecting your GPU, finding model files, processing a face, or generating the expected lip-sync result, start with the exact symptom you see.

This troubleshooting guide is organized by problem rather than installation stage. Use the table below to jump to the relevant check instead of reinstalling everything immediately.

Important: Some fixes on this page come from setups that were directly tested while preparing guides on this site. Other sections are diagnostic checks based on MuseTalk’s current requirements and code. If a fix has not been verified for every operating system or GPU, it is described as a check rather than a guaranteed solution.

Quick MuseTalk Troubleshooting Index

Problem or Error	Check First	Detailed Guide
ffmpeg: command not found or FFmpeg is not recognized	Confirm FFmpeg is installed and available in PATH	MuseTalk FFmpeg Setup
Required model files are missing	Check the models folders and filenames	MuseTalk Model Weights
FileNotFoundError for MuseTalk model files	Confirm whether you are using MuseTalk 1.0 or 1.5 paths	MuseTalk 1.0 vs 1.5
huggingface_hub version error	Check the installed Hugging Face Hub version	Windows Installation Guide
ModuleNotFoundError: No module named 'mmpose' or MMCV install failure	Install pre-built binary MMCV wheels matching PyTorch 2.0.1+cu118	MMCV Version Checks & Fix
Chumpy installation fails	Install Chumpy without build isolation	MuseTalk Installation Guide
CUDA is unavailable	Check nvidia-smi and torch.cuda.is_available()	MuseTalk Installation Guide
CUDA out of memory	Enable FP16, reduce batch size, and check physical card limits	CUDA Out of Memory Guide
No face detected	Check face angle, size, lighting, and bounding box	Single Photo Guide
Mouth position or blending looks wrong	Check face crop and MuseTalk 1.5 inpainting settings	Lip-Sync Tutorial
Single photo output looks static	Understand what MuseTalk changes in a still image	Single Photo Guide
ComfyUI MuseTalk node is missing	Restart ComfyUI and verify the custom node directory	MuseTalk ComfyUI Guide
Google Colab setup fails	Find the first notebook cell that failed	MuseTalk Colab Guide
Gradio interface does not open	Check terminal errors before troubleshooting the browser	MuseTalk Gradio Guide

Before Changing Anything: Run These Basic Checks

When MuseTalk fails, keep the terminal open and copy the complete error. The last line alone often does not show what caused the problem.

Then confirm that you are running commands from the MuseTalk project directory and inside the Python environment you used during installation.

1. Check Python

python --version

If you installed MuseTalk inside Conda, also check which environment is active:

conda env list

The active environment normally has an asterisk beside it.

On macOS or Linux:

which python

On Windows:

where python

If the returned Python executable belongs to a different environment, activate the correct MuseTalk environment before installing more packages.

2. Check FFmpeg

ffmpeg -version

If FFmpeg information appears, the command is accessible. If the terminal reports that FFmpeg cannot be found, go directly to the MuseTalk FFmpeg setup guide.

3. Check PyTorch and CUDA

python -c "import torch; print('PyTorch:', torch.__version__); print('CUDA available:', torch.cuda.is_available()); print('CUDA version:', torch.version.cuda)"

If CUDA available prints True, also check which GPU PyTorch sees:

python -c "import torch; print(torch.cuda.get_device_name(0))"

Do not immediately reinstall CUDA when this check fails. First compare your Python, PyTorch, driver, and installation route with the MuseTalk installation guide.

4. Check the Model Directory

On Linux or macOS:

find ./models -type f | sort

On Windows CMD:

dir models /s /b

Compare the result with the complete folder structure in the MuseTalk model weights guide.

Fix: ffmpeg: command not found

MuseTalk checks whether the ffmpeg executable can be called before inference. If it cannot find FFmpeg, video or audio processing may fail before generation starts.

Check FFmpeg First

ffmpeg -version

If the command returns version information, FFmpeg is accessible.

If you receive an error such as:

'ffmpeg' is not recognized as an internal or external command

or:

ffmpeg: command not found

you need to install FFmpeg or correct its PATH.

Windows: Test the Full FFmpeg Path

Find the folder containing ffmpeg.exe. For example:

C:\ffmpeg\ffmpeg-9.0.2-essentials_build\bin\ffmpeg.exe

Then test it:

C:\ffmpeg\ffmpeg-9.0.2-essentials_build\bin\ffmpeg.exe -version

If that works but ffmpeg -version does not, your FFmpeg installation exists but the bin folder is not available in PATH.

You can temporarily add it in Command Prompt:

set PATH=C:\ffmpeg\ffmpeg-9.0.2-essentials_build\bin;%PATH%

Then check again:

ffmpeg -version

This exact Windows PATH problem was encountered during our Windows MuseTalk installation test. See the tested Windows MuseTalk installation guide for the complete setup.

Linux

On Ubuntu or Debian-based systems, FFmpeg can normally be installed with:

sudo apt update
sudo apt install -y ffmpeg
ffmpeg -version

For more detail, see How to Configure FFmpeg for MuseTalk.

Fix: MuseTalk Says Required Model Files Are Missing

MuseTalk depends on several model files rather than one checkpoint. A missing MuseTalk UNet, VAE, Whisper model, DWPose file, or face parsing file can stop startup or inference.

The current application checks required files before continuing, so a missing-model message should be treated as a file-placement or download problem before changing Python packages.

Run the Official Download Script

From the MuseTalk repository directory on Windows:

download_weights.bat

In PowerShell:

.\download_weights.bat

On Linux:

bash download_weights.sh

Then Inspect the Models Folder

For MuseTalk 1.5, important files include:

models/
├── musetalkV15/
│   ├── musetalk.json
│   └── unet.pth
├── sd-vae/
├── whisper/
├── dwpose/
└── face-parse-bisent/

Do not assume a successful download means every file is in the correct location. A common problem is an extra nested directory such as:

models/models/musetalkV15/

when the program expects:

models/musetalkV15/

See the MuseTalk model download and folder setup guide for the complete file list and verification steps.

Fix: MuseTalk 1.0 and MuseTalk 1.5 Model Path Mismatch

MuseTalk 1.0 and MuseTalk 1.5 use different generator files.

MuseTalk 1.0 uses:

models/musetalk/musetalk.json
models/musetalk/pytorch_model.bin

MuseTalk 1.5 uses:

models/musetalkV15/musetalk.json
models/musetalkV15/unet.pth

If you have MuseTalk 1.5 weights but run a command pointing to the 1.0 directory, MuseTalk may report that the checkpoint cannot be found.

For MuseTalk 1.5, confirm that your command or configuration points to:

--unet_model_path models/musetalkV15/unet.pth
--unet_config models/musetalkV15/musetalk.json
--version v15

Read MuseTalk 1.0 vs MuseTalk 1.5 before changing model filenames manually.

Fix: Hugging Face Hub Version Conflict

During our tested Windows installation, running the model download script upgraded huggingface_hub to a version that conflicted with the installed Transformers version.

If you see an error similar to:

ImportError: huggingface-hub>=0.19.3,<1.0 is required

first check the installed version:

python -c "import huggingface_hub; print(huggingface_hub.__version__)"

In our tested Windows setup, the working correction was:

pip uninstall huggingface_hub -y
pip install huggingface_hub==0.36.2

Then start MuseTalk again.

Do not apply this version change to an unrelated working environment just because the package version is different. Use it when your error specifically indicates a Hugging Face Hub compatibility problem.

The full tested sequence is available in the MuseTalk Windows installation guide.

Fix: MMCV Install Errors & ModuleNotFoundError: No module named 'mmpose'

If MuseTalk fails during installation with a compiler error in torch/utils/cpp_extension.py, reports ModuleNotFoundError: No module named 'mmcv._ext', or fails with:

ModuleNotFoundError: No module named 'mmpose'

this is almost always caused by an ABI mismatch between your PyTorch version and the OpenMMLab packages. Standard PyPI does not host pre-compiled CUDA wheels for MMCV, causing pip install mmcv to attempt a source compilation that fails against host CUDA compilers.

First, verify what is currently installed in your active environment:

python -c "import mmcv; print('MMCV:', mmcv.__version__); import mmpose; print('MMPose:', mmpose.__version__)"

If MMCV is missing or fails to import compiled extensions (mmcv._ext), install the verified pre-built binary wheel matching PyTorch 2.0.1+cu118 directly from OpenMMLab:

pip install mmcv==2.0.1 \
    --find-links https://download.openmmlab.com/mmcv/dist/cu118/torch2.0/index.html \
    --only-binary mmcv
pip install mmengine==0.10.7 mmdet==3.1.0 mmpose==1.1.0

Avoid installing mmcv-lite as a fallback; it omits the CUDA operators required by DWPose and MMPose.

For the complete tested version compatibility matrix, reproduction logs on RTX 4090 hardware, and verification scripts, consult the dedicated MuseTalk MMCV Install Errors & Version Guide. You can also refer to the MuseTalk installation guide, the Colab setup, or the Windows installation guide.

Fix: Chumpy Installation Fails

If installation fails while building Chumpy, try installing it without build isolation:

pip install chumpy --no-build-isolation

Then continue with the remaining dependencies rather than starting the entire installation again.

If the error remains, confirm that pip belongs to your active MuseTalk Python environment:

python -m pip --version

Using:

python -m pip

can also help avoid accidentally calling a pip executable from another Python installation.

Fix: CUDA Is Not Available in MuseTalk

If MuseTalk starts but does not detect your NVIDIA GPU, check the problem in two stages.

Step 1: Check the NVIDIA Driver

nvidia-smi

If this command does not work, solve the driver or GPU-access problem first.

Step 2: Check PyTorch

python -c "import torch; print(torch.__version__); print(torch.version.cuda); print(torch.cuda.is_available())"

If the final value is:

False

then the Python environment currently running MuseTalk does not have usable CUDA access.

If it is:

True

check the GPU name:

python -c "import torch; print(torch.cuda.get_device_name(0))"

A driver working in nvidia-smi does not automatically prove that your current PyTorch environment can use CUDA. Treat those as separate checks.

Compare your environment with the tested setup in the MuseTalk installation guide.

Fix: CUDA Out of Memory

A CUDA out-of-memory error means a GPU allocation failed because enough VRAM was not available for that operation.

First check current GPU memory use:

nvidia-smi

Close unrelated GPU applications or processes if they are occupying a large amount of memory.

Use Half Precision (–use_float16) and Reduce Batch Size

The single most effective fix for CUDA OOM is enabling half precision (--use_float16), which cuts the UNet weight footprint from ~3.4 GB down to ~1.7 GB and drops peak allocated VRAM by over 2.2 GB.

Additionally, decrease the batch size from the default of 8 to 2 or 1 to minimize activation tensor overhead:

python -m scripts.inference --use_float16 --batch_size 2

To eliminate allocator heap fragmentation, also set:

export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True

For detailed measured benchmarks, physical 4 GB card limits, and cloud GPU fallback routes, read our complete MuseTalk CUDA Out of Memory Guide.

Reduce MuseTalk Batch Size

The current MuseTalk inference script exposes a --batch_size option. Standard inference uses a default batch size of 8 in the current script.

If you are launching inference manually, try a smaller value such as:

--batch_size 4

If memory still runs out:

--batch_size 2

or:

--batch_size 1

Reducing batch size can reduce memory demand, although generation may take longer.

Also Check Your Input

If the error occurs only with a particular long or high-resolution video, test a shorter input first. This helps separate a basic installation problem from a workload-related memory problem.

If you are using ComfyUI, follow the memory settings in the MuseTalk ComfyUI guide rather than applying command-line settings to the ComfyUI backend.

Fix: MuseTalk Says No Face Was Detected

MuseTalk’s face-processing stage requires a detectable face in the source image or video. The current application can report:

No face detected, please adjust bbox_shift parameter

Before changing packages, inspect the source media.

Try These Checks

1. Use a face that is clearly visible.
2. Prefer a front-facing or moderately angled face.
3. Avoid very small faces occupying only a tiny part of the frame.
4. Avoid heavy motion blur.
5. Avoid strong obstruction around the eyes, nose, or mouth.
6. Try a tighter crop around the subject.
7. Try another frame or photo to determine whether the problem is input-specific.

If detection works but the crop around the mouth is not correct, adjust the available bounding-box or inpainting controls gradually rather than changing several values at once.

For still images, follow the examples in How to Use MuseTalk With a Single Photo.

Fix: Mouth Area Looks Wrong, Blurry, or Poorly Positioned

If MuseTalk completes generation but the mouth area does not blend well with the rest of the face, the installation may already be working. The problem can instead be related to face size, crop position, input quality, or inpainting parameters.

Test With a Better Input First

Use a clear face that occupies a reasonable part of the frame. A very small face gives the lip-generation area less source detail to work with.

Check the Bounding Box

MuseTalk exposes face-region controls including bbox_shift. MuseTalk 1.5 also has options related to the lower face and blending region.

Change one parameter at a time and compare the result.

Do not assume a larger value is always better. The appropriate crop depends on the person’s face, pose, framing, and source material.

For a complete input-to-output example, see How to Lip Sync a Video Using MuseTalk.

Fix: Lip Sync Works but the Result Does Not Look Right

If a video is produced successfully, first separate a technical failure from an output-quality problem.

If MuseTalk:

• loads the models,
• detects the face,
• processes the audio, and
• saves a final video,

then reinstalling Python is usually not the first troubleshooting step.

Instead check:

• face size in the source video,
• face angle,
• lighting around the mouth,
• audio clarity,
• source frame rate,
• bounding-box settings, and
• whether you are using MuseTalk 1.0 or MuseTalk 1.5.

The official MuseTalk documentation recommends 25 fps input for best alignment with the frame rate used during training.

You can inspect a video’s frame rate with FFmpeg:

ffmpeg -i input.mp4

If you need a complete generation walkthrough, use the MuseTalk video lip-sync tutorial.

Fix: Single Photo Output Looks Like a Static Picture With a Moving Mouth

This can be expected behavior rather than an installation problem.

MuseTalk focuses on modifying the lip and lower-face region according to audio. Starting with one still photograph does not automatically give you natural head movement, blinking, body movement, or changing camera perspective.

If you want to test whether your installation is working, use a clear front-facing portrait and short speech audio first.

You can also convert a still image into a fixed-frame-rate video before processing it:

ffmpeg -loop 1 -i portrait.png -c:v libx264 -t 10 -pix_fmt yuv420p -r 25 output.mp4

Change -t 10 to match the approximate duration you need.

See How to Use MuseTalk With a Single Photo for the full workflow.

Fix: MuseTalk Output Duration Does Not Match the Audio

First determine whether the issue comes from your source video, converted photo video, or audio duration.

Check the audio:

ffmpeg -i speech.wav

Check the video:

ffmpeg -i input.mp4

If you manually created a video from a still image with:

-t 10

then that source was explicitly limited to 10 seconds.

Make the generated source video at least as long as the speech audio before running MuseTalk again.

Fix: MuseTalk Gradio Interface Does Not Open

If you start MuseTalk but cannot access the browser interface, check the terminal before changing browser settings.

If MuseTalk fails while loading models or Python dependencies, the Gradio server may never start.

Check the Terminal for One of These Problems

• missing model files,
• missing Python modules,
• FFmpeg warnings,
• CUDA errors,
• Hugging Face version conflicts, or
• an address or port error.

On a successful local Gradio startup, MuseTalk normally prints the local address it is serving. Open the exact address shown by your terminal rather than assuming a port.

For browser-based operation, see How to Use the MuseTalk Gradio Web Demo.

Fix: Google Colab Does Not Detect a GPU

If you are using the MuseTalk Colab workflow, start by checking the runtime rather than reinstalling packages.

Run:

!nvidia-smi

If no NVIDIA GPU appears, switch the notebook to a GPU runtime and run the setup again from the beginning.

Our MuseTalk Colab workflow separates environment setup, CUDA checks, model downloads, and input upload into numbered cells. If a later cell fails, find the first cell that reported an error instead of repeatedly running the final generation cell.

Use the complete MuseTalk Google Colab setup guide for the tested notebook sequence.

Fix: Model Download Fails in Google Colab

If a model download stops because of a network or runtime interruption, first check whether the files that completed are still present.

Then rerun the model-download step rather than rebuilding unrelated dependencies.

In our Colab workflow, the model step verifies the required files before inference. Follow the instructions in the MuseTalk Colab guide.

Fix: MuseTalk Node Does Not Appear in ComfyUI

If MuseTalk was installed as a ComfyUI custom node but the node does not appear, verify that the custom node files exist in the expected ComfyUI directory.

Then restart the ComfyUI backend.

Refreshing the browser alone does not reload Python custom nodes that are discovered when the server starts.

In our tested ComfyUI setup, the backend can also be queried to check whether the MuseTalk node registered correctly.

Follow the exact package layout and restart steps in the MuseTalk ComfyUI setup guide.

Fix: ComfyUI MuseTalk Reports CUDA Out of Memory

If standalone MuseTalk works but the ComfyUI workflow runs out of VRAM, remember that other loaded ComfyUI models may also be occupying GPU memory.

Check:

• whether another large model is loaded,
• input resolution,
• video duration,
• MuseTalk batch settings, and
• whether the workflow provides a lower-memory preset.

The tested MuseTalk ComfyUI workflow includes a low-memory configuration. See MuseTalk in ComfyUI for the current setup and troubleshooting table.

Fix: ComfyUI Workflow Opens but Uploaded Media Is Missing

A workflow JSON primarily stores workflow configuration and node connections. Do not assume that copying a workflow JSON to another computer also copies your uploaded video, audio, model weights, or backend installation.

On the new machine:

1. Install the required MuseTalk backend and custom node.
2. Download the required model files.
3. Restart ComfyUI.
4. Open the workflow.
5. Upload the input face and audio again.

See the MuseTalk ComfyUI guide for the workflow files and setup details.

Fix: MuseTalk Is Very Slow

First check whether MuseTalk is actually using the NVIDIA GPU.

python -c "import torch; print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'No CUDA GPU')"

While generation is running, open another terminal and monitor the GPU:

nvidia-smi -l 1

Watch GPU utilization and memory usage.

If the GPU remains almost unused while generation is running, inspect your CUDA and PyTorch environment.

If the GPU is being used normally, generation time can still vary based on video length, hardware, input processing, batch size, and output settings.

Do Not Reinstall Everything for Every MuseTalk Error

A useful troubleshooting order is:

1. Copy the exact error.
2. Confirm the correct Python environment.
3. Check FFmpeg.
4. Check the model files.
5. Check PyTorch and CUDA.
6. Test with a short, clear input.
7. Only change the component connected to the error.

For example, a missing unet.pth file is primarily a model-file problem. Reinstalling CUDA is unlikely to be the correct first response.

Similarly, a ffmpeg: command not found error should be resolved at the FFmpeg or PATH level before changing PyTorch.

Which MuseTalk Guide Should You Use Next?

Your Goal	Guide
Install MuseTalk	MuseTalk Installation Guide
Install MuseTalk on Windows	MuseTalk Windows Installation
Fix FFmpeg setup	MuseTalk FFmpeg Guide
Download or verify checkpoints	MuseTalk Model Weights
Run MuseTalk in ComfyUI	MuseTalk ComfyUI Guide
Run MuseTalk in Google Colab	MuseTalk Colab Guide
Use a single photo	MuseTalk Photo + Audio Tutorial
Lip-sync an existing video	MuseTalk Video Lip-Sync Tutorial
Choose MuseTalk 1.0 or 1.5	MuseTalk 1.0 vs 1.5
Test MuseTalk before installing	MuseTalk Playground

Still Getting an Error?

If your problem is not listed above, save these details before changing your installation:

• complete error message,
• operating system,
• Python version,
• PyTorch version,
• CUDA version reported by PyTorch,
• GPU model,
• MuseTalk version: 1.0 or 1.5,
• the command you ran, and
• whether the error happens during startup, preprocessing, inference, or final video creation.

You can collect several of those details with:

python --version
ffmpeg -version
nvidia-smi
python -c "import torch; print('PyTorch:', torch.__version__); print('CUDA:', torch.version.cuda); print('Available:', torch.cuda.is_available()); print('GPU:', torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'None')"

This information makes it much easier to determine whether the problem is related to the environment, GPU, model files, FFmpeg, input media, or MuseTalk itself.

If you have not completed a successful installation yet, return to the MuseTalk installation guide and follow the route for your operating system and hardware.