GitHub - chyinan/uvr-headless-runner: Production-ready UVR5 CLI & Docker image. Run SOTA separation models (Roformer, SCNet, MDX, Demucs, VR Architecture) on headless GPU servers without dependency hell.

UVR Headless Runner

🎧 Separate vocals, instruments, drums, bass & more from any audio

Command-line audio source separation powered by UVR

🇨🇳 中文 | 🇬🇧 English | 🐳 Docker

✨ Features

🎸 MDX-Net Runner

MDX-Net / MDX-C models
Roformer (MelBandRoformer, BSRoformer)
SCNet (Sparse Compression Network)
ONNX & PyTorch checkpoints

🥁 Demucs Runner

Demucs v1 / v2 / v3 / v4
htdemucs / htdemucs_ft
6-stem separation (Guitar, Piano)
Auto model download

🎤 VR Runner

VR Architecture models
VR 5.1 model support
Window size / Aggression tuning
TTA & Post-processing

🚀 Highlights

Feature	Description
🎯 GUI-Identical	Exactly replicates UVR GUI behavior
⚡ GPU Accelerated	NVIDIA CUDA & AMD DirectML support
🔧 Zero Config	Auto-detect model parameters
📦 Batch Ready	Perfect for automation & pipelines
🎚️ Bit Depth Control	16/24/32-bit PCM, 32/64-bit float
📥 Auto Download	Official UVR model registry with auto-download
🛡️ Robust Error Handling	GPU fallback, retry, fuzzy matching
🔗 Unified CLI	`uvr mdx` / `uvr demucs` / `uvr vr` — one command for all
📦 PyPI Ready	`pip install uvr-headless-runner` — instant setup

📖 Design Philosophy

This project is a headless automation layer for Ultimate Vocal Remover.

It does NOT reimplement any separation logic.
It EXACTLY REPLICATES UVR GUI behavior — model loading, parameter fallback, and auto-detection.

✅ If a model works in UVR GUI, it works here — no extra config needed.

🤔 Why uvr-headless-runner?

Built for maximum flexibility. Load any custom model without waiting for upstream updates.

🎨 Full Custom Model Support

Directly load any .pth or .ckpt file.
Perfect for testing new finetunes or experimental models immediately.

🖥️ Headless & Remote Ready

Built for seamless integration into
web services or automation scripts.

👥 By Users, For Users

Designed by audio enthusiasts who
prioritize complete control and native UVR compatibility.

📋 Requirements

Component	Requirement
Python	3.9.x (3.10+ not fully tested)
GPU	NVIDIA CUDA or AMD DirectML (optional)
OS	Windows / Linux / macOS

🔧 Installation

🚀 Option 1: pip install from PyPI (Recommended)

# Install from PyPI
pip install uvr-headless-runner

# GPU support (NVIDIA)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124

# ONNX GPU (optional)
pip install onnxruntime-gpu

After installation, you get the uvr unified CLI — no need to clone the repo!

uvr mdx -m "UVR-MDX-NET Inst HQ 3" -i song.wav -o output/
uvr demucs -m htdemucs -i song.wav -o output/
uvr vr -m "UVR-De-Echo-Normal" -i song.wav -o output/

📦 Option 2: Poetry (from source)

# Clone repository
git clone https://github.com/chyinan/uvr-headless-runner.git
cd uvr-headless-runner

# Install dependencies
poetry install

# GPU support (NVIDIA)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124

# ONNX GPU (optional)
pip install onnxruntime-gpu

📦 Option 3: pip + venv (from source)

# Clone repository
git clone https://github.com/chyinan/uvr-headless-runner.git
cd uvr-headless-runner

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate   # Windows

# Install dependencies
pip install -r requirements.txt

# GPU support (NVIDIA)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124

🔴 AMD GPU (DirectML)

# Install DirectML support
pip install torch-directml

# Use with --directml flag
python mdx_headless_runner.py -m model.ckpt -i song.wav -o output/ --directml

⚠️ DirectML is experimental. NVIDIA CUDA recommended for best performance.

✅ Verify Installation (Native Python Only)

python -c "import torch; print(f'PyTorch: {torch.__version__}'); print(f'CUDA: {torch.cuda.is_available()}')"

💡 Skip this if using Docker - the container includes all dependencies.

🐳 Option 4: Docker Hub (No Build Required!)

Fastest way to get started - just pull and run!

# Pull pre-built image from Docker Hub
docker pull chyinan/uvr-headless-runner:latest

# Run directly (GPU mode)
docker run --rm --gpus all \
  -v ~/.uvr_models:/models \
  -v $(pwd):/data \
  chyinan/uvr-headless-runner:latest \
  uvr-mdx -m "UVR-MDX-NET Inst HQ 3" -i /data/song.wav -o /data/output/

# Run directly (CPU mode)
docker run --rm \
  -v ~/.uvr_models:/models \
  -v $(pwd):/data \
  chyinan/uvr-headless-runner:latest \
  uvr-mdx -m "UVR-MDX-NET Inst HQ 3" -i /data/song.wav -o /data/output/ --cpu

Or install CLI wrappers for native experience:

# One-click install (auto-detects GPU)
./docker/install.sh      # Linux/macOS
.\docker\install.ps1     # Windows

# Then use like native commands
uvr-mdx -m "UVR-MDX-NET Inst HQ 3" -i song.wav -o output/
uvr-demucs -m htdemucs -i song.wav -o output/
uvr-vr -m "UVR-De-Echo-Normal" -i song.wav -o output/

📖 Full Docker Guide →

🎼 Quick Start

Unified CLI (pip install / Docker)

After installing via pip install uvr-headless-runner or Docker, you can use the short commands:

# MDX-Net / Roformer separation
uvr mdx -m "UVR-MDX-NET Inst HQ 3" -i song.wav -o output/ --gpu

# Demucs separation
uvr demucs -m htdemucs -i song.wav -o output/ --gpu

# VR Architecture separation
uvr vr -m "UVR-De-Echo-Normal" -i song.wav -o output/ --gpu

# List all available models
uvr list all

# Download a model
uvr download "UVR-MDX-NET Inst HQ 3" --arch mdx

# Show system info
uvr info

💡 You can also use standalone commands: uvr-mdx, uvr-demucs, uvr-vr

MDX-Net / Roformer / SCNet

# Basic separation
python mdx_headless_runner.py -m "model.ckpt" -i "song.flac" -o "output/" --gpu

# Vocals only (24-bit)
python mdx_headless_runner.py -m "model.ckpt" -i "song.flac" -o "output/" --gpu --vocals-only --wav-type PCM_24

Demucs

# All 4 stems
python demucs_headless_runner.py --model htdemucs --input "song.flac" --output "output/" --gpu

# Vocals only
python demucs_headless_runner.py --model htdemucs --input "song.flac" --output "output/" --gpu --stem Vocals --primary-only

VR Architecture

# Basic separation (model in database)
python vr_headless_runner.py -m "model.pth" -i "song.flac" -o "output/" --gpu

# Custom model (not in database)
python vr_headless_runner.py -m "model.pth" -i "song.flac" -o "output/" --gpu \
    --param 4band_v3 --primary-stem Vocals

📥 Model Download Center

All runners now include automatic model downloading from official UVR sources - just like the GUI!

List Available Models

# List all MDX-Net models
python mdx_headless_runner.py --list

# List only installed models
python mdx_headless_runner.py --list-installed

# List models not yet downloaded
python mdx_headless_runner.py --list-uninstalled

# Same for Demucs and VR
python demucs_headless_runner.py --list
python vr_headless_runner.py --list

Download Models

# Download a specific model (without running inference)
python mdx_headless_runner.py --download "UVR-MDX-NET Inst HQ 3"
python demucs_headless_runner.py --download "htdemucs_ft"
python vr_headless_runner.py --download "UVR-De-Echo-Normal by FoxJoy"

Auto-Download on Inference

# Just use the model name - it will download automatically if not installed!
python mdx_headless_runner.py -m "UVR-MDX-NET Inst HQ 3" -i "song.flac" -o "output/" --gpu

# Demucs models auto-download too
python demucs_headless_runner.py --model htdemucs_ft --input "song.flac" --output "output/" --gpu

Model Info & Fuzzy Matching

# Get detailed info about a model
python mdx_headless_runner.py --model-info "UVR-MDX-NET Inst HQ 3"

# Typo? Get suggestions!
python mdx_headless_runner.py --model-info "UVR-MDX Inst HQ"
# Output: Did you mean: UVR-MDX-NET Inst HQ 1, UVR-MDX-NET Inst HQ 2, ...

Features

Feature	Description
🌐 Official Registry	Syncs with UVR's official model list
🔄 Resume Downloads	Interrupted downloads can be resumed
⏱️ Retry with Backoff	Automatic retry on network errors
💾 Disk Space Check	Pre-checks available space before download
🔍 Fuzzy Matching	Suggests similar model names on typos
✅ Integrity Check	Validates downloaded files

🛡️ Error Handling & GPU Fallback

All runners include robust error handling with automatic GPU-to-CPU fallback:

# If GPU runs out of memory, automatically falls back to CPU
python mdx_headless_runner.py -m "model.ckpt" -i "song.flac" -o "output/" --gpu

# Output on GPU error:
# ============================================================
# ERROR: GPU memory exhausted
# ============================================================
# Suggestion: Try: (1) Use --cpu flag, (2) Reduce --batch-size...
#
# Attempting to fall back to CPU mode...

Error Messages

Errors now include clear explanations and suggestions:

Before	After
`FileNotFoundError`	`Audio file not found: song.wav`
`CUDA out of memory`	`GPU memory exhausted. Try: --cpu or reduce --batch-size`
`Model not found`	`Model 'xyz' not found. Did you mean: UVR-MDX-NET...?`

📊 CLI Progress Display

All runners feature a professional CLI progress system with real-time feedback:

╭──────────────────────────────────────────────────────────────────────────╮
│                          UVR Audio Separation                            │
├──────────────────────────────────────────────────────────────────────────┤
│  Model         │ UVR-MDX-NET Inst HQ 3                                   │
│  Input         │ song.flac                                               │
│  Output        │ ./output/                                               │
│  Device        │ CUDA:0                                                  │
│  Architecture  │ MDX-Net                                                 │
╰──────────────────────────────────────────────────────────────────────────╯

⠹ Downloading model: UVR-MDX-NET Inst HQ 3
  ████████████████████████████████████████ 100% • 245.3 MB • 12.5 MB/s • 0:00:00

✓ Model downloaded

⠹ Running inference
  ████████████████░░░░░░░░░░░░░░░░░░░░░░░░  42% • 0:01:23 • 0:01:52

✓ Inference complete

╭──────────────────────────────────────────────────────────────────────────╮
│              ✓ Processing completed in 3:15                              │
╰──────────────────────────────────────────────────────────────────────────╯

Output files:
  • output/song_(Vocals).wav
  • output/song_(Instrumental).wav

Features

Feature	Description
📥 Download Progress	Real-time speed, ETA, and transfer stats for model downloads
🎯 Inference Progress	Chunk-based progress tracking during audio processing
⏱️ Time Estimates	Elapsed time and remaining time (ETA) display
🎨 Rich Output	Beautiful terminal UI with `rich` library
🐳 Docker Compatible	Works seamlessly inside containers
📉 Graceful Fallback	Falls back to basic output if `rich` unavailable

Progress Library Support

The system automatically selects the best available library:

rich (preferred) - Full-featured progress bars with colors
tqdm (fallback) - Standard progress bars
Basic (no deps) - Simple text-based progress

Install rich for the best experience:

pip install rich

Quiet Mode

Disable progress output for scripting:

python mdx_headless_runner.py -m model.ckpt -i song.wav -o output/ --quiet

🎛️ MDX-Net Runner

Command Line Arguments

Argument	Short	Default	Description
`--model`	`-m`	Required	Model file path (.ckpt/.onnx)
`--input`	`-i`	Required	Input audio file
`--output`	`-o`	Required	Output directory
`--gpu`		Auto	Use NVIDIA CUDA
`--directml`			Use AMD DirectML
`--overlap`		`0.25`	MDX overlap (0.25-0.99)
`--overlap-mdxc`		`2`	MDX-C/Roformer overlap (2-50)
`--wav-type`		`PCM_24`	Output: PCM_16/24/32, FLOAT, DOUBLE
`--vocals-only`			Output vocals only
`--instrumental-only`			Output instrumental only

📋 All Arguments

Argument	Description
`--name` `-n`	Output filename base
`--json`	Model JSON config
`--cpu`	Force CPU
`--device` `-d`	GPU device ID
`--segment-size`	Segment size (default: 256)
`--batch-size`	Batch size (default: 1)
`--primary-only`	Save primary stem only
`--secondary-only`	Save secondary stem only
`--stem`	MDX-C stem select
`--quiet` `-q`	Quiet mode

Examples

# Roformer with custom overlap
python mdx_headless_runner.py \
    -m "MDX23C-8KFFT-InstVoc_HQ.ckpt" \
    -i "song.flac" -o "output/" \
    --gpu --overlap-mdxc 8

# 32-bit float output
python mdx_headless_runner.py \
    -m "model.ckpt" -i "song.flac" -o "output/" \
    --gpu --wav-type FLOAT

🥁 Demucs Runner

Supported Models

Model	Version	Stems	Quality
`htdemucs`	v4	4	⭐⭐⭐
`htdemucs_ft`	v4	4	⭐⭐⭐⭐ Fine-tuned
`htdemucs_6s`	v4	6	⭐⭐⭐⭐ +Guitar/Piano
`hdemucs_mmi`	v4	4	⭐⭐⭐
`mdx_extra_q`	v3	4	⭐⭐⭐

Command Line Arguments

Argument	Short	Default	Description
`--model`	`-m`	Required	Model name or path
`--input`	`-i`	Required	Input audio file
`--output`	`-o`	Required	Output directory
`--gpu`		Auto	Use NVIDIA CUDA
`--segment`		Default	Segment size (1-100+)
`--shifts`		`2`	Time shifts
`--stem`			Vocals/Drums/Bass/Other/Guitar/Piano
`--wav-type`		`PCM_24`	Output bit depth
`--primary-only`			Output primary stem only

Stem Selection

GUI Action	CLI Command
All Stems	(no --stem)
Vocals only	`--stem Vocals --primary-only`
Instrumental only	`--stem Vocals --secondary-only`

Examples

# 6-stem separation
python demucs_headless_runner.py \
    --model htdemucs_6s \
    --input "song.flac" --output "output/" \
    --gpu

# High quality with custom segment
python demucs_headless_runner.py \
    --model htdemucs_ft \
    --input "song.flac" --output "output/" \
    --gpu --segment 85

🎤 VR Architecture Runner

Command Line Arguments

Argument	Short	Default	Description
`--model`	`-m`	Required	Model file path (.pth)
`--input`	`-i`	Required	Input audio file
`--output`	`-o`	Required	Output directory
`--gpu`		Auto	Use NVIDIA CUDA
`--directml`			Use AMD DirectML
`--window-size`		`512`	Window size (320/512/1024)
`--aggression`		`5`	Aggression setting (0-50+)
`--wav-type`		`PCM_16`	Output: PCM_16/24/32, FLOAT, DOUBLE
`--primary-only`			Output primary stem only
`--secondary-only`			Output secondary stem only

📋 All Arguments

Argument	Description
`--name` `-n`	Output filename base
`--param`	Model param name (e.g., 4band_v3)
`--primary-stem`	Primary stem name (Vocals/Instrumental)
`--nout`	VR 5.1 nout parameter
`--nout-lstm`	VR 5.1 nout_lstm parameter
`--cpu`	Force CPU
`--device` `-d`	GPU device ID
`--batch-size`	Batch size (default: 1)
`--tta`	Enable Test-Time Augmentation
`--post-process`	Enable post-processing
`--post-process-threshold`	Post-process threshold (default: 0.2)
`--high-end-process`	Enable high-end mirroring
`--list-params`	List available model params

Model Parameters

When the model hash is not found in the database, you need to provide parameters manually:

# List available params
python vr_headless_runner.py --list-params

# Use custom params
python vr_headless_runner.py -m "model.pth" -i "song.flac" -o "output/" \
    --param 4band_v3 --primary-stem Vocals

# VR 5.1 model with nout/nout_lstm
python vr_headless_runner.py -m "model.pth" -i "song.flac" -o "output/" \
    --param 4band_v3 --primary-stem Vocals --nout 48 --nout-lstm 128

Examples

# High quality with TTA
python vr_headless_runner.py \
    -m "UVR-MDX-NET-Voc_FT.pth" \
    -i "song.flac" -o "output/" \
    --gpu --tta --window-size 1024

# Aggressive separation
python vr_headless_runner.py \
    -m "model.pth" -i "song.flac" -o "output/" \
    --gpu --aggression 15 --post-process

# 24-bit output
python vr_headless_runner.py \
    -m "model.pth" -i "song.flac" -o "output/" \
    --gpu --wav-type PCM_24

📁 Output Structure

output/
├── song_(Vocals).wav        # Vocals
├── song_(Instrumental).wav  # Instrumental (MDX)
├── song_(Drums).wav         # Drums (Demucs)
├── song_(Bass).wav          # Bass (Demucs)
├── song_(Other).wav         # Other (Demucs)
├── song_(Guitar).wav        # Guitar (6-stem)
└── song_(Piano).wav         # Piano (6-stem)

🐍 Python API

from mdx_headless_runner import run_mdx_headless
from demucs_headless_runner import run_demucs_headless
from vr_headless_runner import run_vr_headless

# MDX separation
run_mdx_headless(
    model_path='model.ckpt',
    audio_file='song.wav',
    export_path='output',
    use_gpu=True,
    verbose=True  # Print progress
)
# Output: output/song_(Vocals).wav, output/song_(Instrumental).wav

# Demucs separation (vocals only)
run_demucs_headless(
    model_path='htdemucs',
    audio_file='song.wav',
    export_path='output',
    use_gpu=True,
    demucs_stems='Vocals',  # or 'All Stems' for all
    primary_only=True,
    verbose=True
)
# Output: output/song_(Vocals).wav

# VR Architecture separation
run_vr_headless(
    model_path='model.pth',
    audio_file='song.wav',
    export_path='output',
    use_gpu=True,
    window_size=512,
    aggression_setting=5,
    is_tta=False,
    # For unknown models, provide params manually:
    # user_vr_model_param='4band_v3',
    # user_primary_stem='Vocals'
)
# Output: output/song_(Vocals).wav, output/song_(Instrumental).wav

💡 Note: Functions process audio and save to export_path. Check output directory for results.

🔍 Troubleshooting

❌ GPU not detected

# Check CUDA
python -c "import torch; print(torch.cuda.is_available())"

# Reinstall PyTorch with CUDA
pip uninstall torch torchvision torchaudio
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124

❌ Model not found

Option 1: Use automatic download (recommended)

# List available models
python mdx_headless_runner.py --list

# Download the model
python mdx_headless_runner.py --download "UVR-MDX-NET Inst HQ 3"

# Or just use it - auto-downloads!
python mdx_headless_runner.py -m "UVR-MDX-NET Inst HQ 3" -i song.wav -o output/

Option 2: Manual download

Default locations:

MDX: ./models/MDX_Net_Models/
Demucs: ./models/Demucs_Models/v3_v4_repo/
VR: ./models/VR_Models/

❌ Network/Download errors

# Force refresh model registry
python model_downloader.py --sync

# Check network connectivity
python -c "import urllib.request; urllib.request.urlopen('https://github.com')"

The downloader includes:

Automatic retry (3 attempts with exponential backoff)
Resume interrupted downloads
Fallback to cached registry

❌ VR model hash not found

If your VR model isn't in the database, provide parameters manually:

# List available params
python vr_headless_runner.py --list-params

# Specify param and primary stem
python vr_headless_runner.py -m "model.pth" -i "song.wav" -o "output/" \
    --param 4band_v3 --primary-stem Vocals

Common params: 4band_v3, 4band_v2, 1band_sr44100_hl512, 3band_44100

❌ Poor output quality

Try increasing --overlap or --overlap-mdxc
For Demucs, increase --segment (e.g., 85)
Ensure correct model config with --json

🙏 Acknowledgments

_{Anjok07 & aufr33}

_{Facebook Research}

_{Woosung Choi}

_tsurumeso

Special thanks to ZFTurbo for MDX23C & SCNet.

📄 License

MIT License

Copyright (c) 2022 Anjok07 (Ultimate Vocal Remover)
Copyright (c) 2026 UVR Headless Runner Contributors

View Full License

Contributing & Support

Pull Requests and Issues are welcome! Whether it's bug reports, feature suggestions, or code contributions, we greatly appreciate them all.

If you find this project helpful, please give us a Star ⭐ - it's the best support for us!

_{Made with ❤️ for the audio separation community}

Name		Name	Last commit message	Last commit date
Latest commit History 35 Commits
.github		.github
.model_cache		.model_cache
demucs		demucs
docker		docker
gui_data		gui_data
lib_v5		lib_v5
models		models
tests		tests
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
DOCKER_README.md		DOCKER_README.md
DOCKER_README_CN.md		DOCKER_README_CN.md
LICENSE		LICENSE
README.md		README.md
README_CN.md		README_CN.md
UVR.py		UVR.py
__version__.py		__version__.py
cli.py		cli.py
demucs_headless_runner.py		demucs_headless_runner.py
download_checks_sample.json		download_checks_sample.json
error_handler.py		error_handler.py
mdx_headless_runner.py		mdx_headless_runner.py
model_downloader.py		model_downloader.py
poetry		poetry
progress.py		progress.py
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
separate.py		separate.py
vr_headless_runner.py		vr_headless_runner.py

License

chyinan/uvr-headless-runner

Folders and files

Latest commit

History

Repository files navigation

🎧 Separate vocals, instruments, drums, bass & more from any audio

✨ Features

🎸 MDX-Net Runner

🥁 Demucs Runner

🎤 VR Runner

🚀 Highlights

📖 Design Philosophy

🤔 Why uvr-headless-runner?

🎨 Full Custom Model Support

🖥️ Headless & Remote Ready

👥 By Users, For Users

📋 Requirements

🔧 Installation

✅ Verify Installation (Native Python Only)

🎼 Quick Start

Unified CLI (pip install / Docker)

MDX-Net / Roformer / SCNet

Demucs

VR Architecture

📥 Model Download Center

List Available Models

Download Models

Auto-Download on Inference

Model Info & Fuzzy Matching

Features

🛡️ Error Handling & GPU Fallback

Error Messages

📊 CLI Progress Display

Features

Progress Library Support

Quiet Mode

🎛️ MDX-Net Runner

Command Line Arguments

Examples

🥁 Demucs Runner

Supported Models

Command Line Arguments

Stem Selection

Examples

🎤 VR Architecture Runner

Command Line Arguments

Model Parameters

Examples

📁 Output Structure

🐍 Python API

🔍 Troubleshooting

🙏 Acknowledgments

📄 License

Contributing & Support

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages