🎵 Ultimate Vocal Remover — A state-of-the-art AI-powered audio source separation tool.
This application uses state-of-the-art source separation models to remove vocals from audio files. UVR's core developers trained all of the models provided in this package (except for the Demucs v3 and v4 4-stem models).
| Role | Developer |
|---|---|
| Original Author | Anjok07 |
| Original Author | aufr33 |
| Fork Maintainer | kasc0206 |
This fork (kasc0206/uvrgui) extends the original UVR with:
- 🖥️ CLI Tool —
uvr_cli.pywith 10 commands for headless operation - ✅ Lint Clean — All ruff checks pass (zero errors on custom code)
- 🧪 Test Suite — 32 tests with pytest + coverage reporting
- 🐛 Bug Fixes — Fixed
highlightthicknestypo, star imports, Pylance type errors - 📖 Chinese Documentation — Full README_zh.md
This fork adds uvr_cli.py, a full-featured command-line interface:
# List all available models with download status
python uvr_cli.py list
# List models as JSON (for programmatic use)
python uvr_cli.py list --json
# Show model details
python uvr_cli.py info <keyword>
# Launch the GUI
python uvr_cli.py gui
# View or modify configuration
python uvr_cli.py config
python uvr_cli.py config --key default_device --value mps
# Process audio with Demucs (auto-downloads models)
python uvr_cli.py process song.mp3
python uvr_cli.py demucs song.flac --two-stem vocals
python uvr_cli.py process input_dir/ --out output_dir/
# Download Demucs models via curl (500x faster)
python uvr_cli.py download-models
# Check version
python uvr_cli.py version
# Show help
python uvr_cli.py help
⚠️ 注意:本 Fork 不提供预编译安装包。请按照以下步骤从源码构建。
# 1. 克隆仓库
git clone https://github.com/kasc0206/uvrgui.git
cd uvrgui
# 2. 创建虚拟环境
python3 -m venv venv
source venv/bin/activate # Linux/macOS
# 或 venv\Scripts\activate # Windows
# 3. 安装依赖
pip install -r requirements.txt
# 4. NVIDIA GPU 用户安装 CUDA PyTorch(可选)
pip install --upgrade torch --extra-index-url https://download.pytorch.org/whl/cu118
# 5. 启动
python UVR.py本 Fork 支持通过 GitHub Actions 自动构建 Windows EXE。推送 tag 即可触发:
git tag v1.0.0
git push origin v1.0.0也可手动触发:Actions 页面
每次推送 tag 后,CI 会自动构建两个版本:
| 变体 | 文件 | 体积 | GPU | Release 附件 | Artifact |
|---|---|---|---|---|---|
| CPU 版 | UVR_*_CPU.zip |
~400 MB | ❌ | ✅ 直接下载 | ✅ |
| CUDA 版 | UVR_*_CUDA.zip |
~2.5 GB | ✅ NVIDIA | ❌ 超 2GB 限制 | ✅ |
CI 流程:
- 先安装 CPU PyTorch → 编译 CPU 版 → 打包 ZIP → 上传 Artifact
- 再安装 CUDA PyTorch → 重新编译 CUDA 版 → 打包 ZIP → 上传 Artifact
- Release 页面:CPU 版作为附件直接下载,CUDA 版提供 Artifact 链接
pip install -r requirements.txt
pip install pyinstaller
# CPU 版(默认)
pyinstaller UVR.spec --clean --noconfirm
# CUDA 版(需先安装 CUDA PyTorch)
pip install --upgrade torch --extra-index-url https://download.pytorch.org/whl/cu121
pyinstaller UVR.spec --clean --noconfirm- macOS Big Sur (11) 或更高版本
- 约 10 GB 磁盘空间(含 PyTorch 运行时)
- Xcode Command Line Tools
# 1. 安装 Xcode Command Line Tools
xcode-select --install
# 2. 安装 Homebrew(如尚未安装)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 3. 安装系统依赖
brew install ffmpeg python@3.10
# 4. 可选 — 安装 Rubber Band(变调变速功能)
brew install rubberband
# 5. 克隆仓库
git clone https://github.com/kasc0206/uvrgui.git
cd uvrgui
# 6. 创建虚拟环境
python3.10 -m venv venv
source venv/bin/activate
# 7. 安装依赖
pip install --upgrade pip wheel setuptools
pip install -r requirements.txt
# 8. 启动
python UVR.py首次启动可能需要 5-10 分钟(模型初始化)。
Apple Silicon (M1/M2/M3):PyTorch MPS 加速自动启用,无需额外配置。
如果遇到「无法验证开发者」提示:
sudo spctl --master-disable sudo xattr -rd com.apple.quarantine /Applications/Ultimate\ Vocal\ Remover.app
- 64 位 Linux 发行版
- 约 10 GB 磁盘空间(含 PyTorch 运行时)
- NVIDIA GPU 用户:CUDA Toolkit 11.8+(可选)
# 1. 更新系统
sudo apt update && sudo apt upgrade -y
# 2. 安装系统依赖
sudo apt install -y ffmpeg python3-pip python3-tk python3-venv
# 3. 可选 — 安装 Rubber Band(变调变速功能)
sudo apt install -y rubberband-cli
# 4. 克隆仓库
git clone https://github.com/kasc0206/uvrgui.git
cd uvrgui
# 5. 创建虚拟环境
python3 -m venv venv
source venv/bin/activate
# 6. 安装 Python 依赖
pip install --upgrade pip wheel setuptools
pip install -r requirements.txt
# 7. NVIDIA GPU 用户安装 CUDA PyTorch(可选)
pip install --upgrade torch --extra-index-url https://download.pytorch.org/whl/cu118
# 8. 启动
python UVR.py# 1. 更新系统
sudo pacman -Syu
# 2. 安装系统依赖
sudo pacman -S ffmpeg python-pip tk python-virtualenv
# 3. 可选 — 安装 Rubber Band(变调变速功能)
sudo pacman -S rubberband
# 4. 克隆仓库
git clone https://github.com/kasc0206/uvrgui.git
cd uvrgui
# 5. 创建虚拟环境
python -m venv venv
source venv/bin/activate
# 6. 安装依赖
pip install --upgrade pip wheel setuptools
pip install -r requirements.txt
# 7. 启动
python UVR.py# 1. 安装系统依赖
sudo dnf install -y ffmpeg python3-pip python3-tkinter python3-virtualenv
# 2. 可选 — 安装 Rubber Band
sudo dnf install -y rubberband
# 3. 克隆仓库
git clone https://github.com/kasc0206/uvrgui.git
cd uvrgui
# 4. 创建虚拟环境
python3 -m venv venv
source venv/bin/activate
# 5. 安装依赖
pip install --upgrade pip wheel setuptools
pip install -r requirements.txt
# 6. 启动
python UVR.pysudo spctl --master-disable
sudo xattr -rd com.apple.quarantine /path/to/UVRMacOS Users: Having Trouble Opening UVR?
Due to Apples strict application security, you may need to follow these steps to open UVR.
First, run the following command via Terminal.app to allow applications to run from all sources (it's recommended that you re-enable this once UVR opens properly.)
sudo spctl --master-disableSecond, run the following command to bypass Notarization:
sudo xattr -rd com.apple.quarantine /Applications/Ultimate\ Vocal\ Remover.app
Manual MacOS Installation
- Download and save this repository here
- Download and install Python 3.10 here
- From the saved directory run the following -
pip3 install -r requirements.txt
- If your Mac is running with an M1, please run the following command next. If not, skip this step. -
cp /Library/Frameworks/Python.framework/Versions/3.10/lib/python3.10/site-packages/_soundfile_data/libsndfile_arm64.dylib /Library/Frameworks/Python.framework/Versions/3.10/lib/python3.10/site-packages/_soundfile_data/libsndfile.dylib
FFmpeg Installation
- Once everything is done installing, download the correct FFmpeg binary for your system here and place it into the main application directory.
Rubber Band Installation
In order to use the Time Stretch or Change Pitch tool, you'll need Rubber Band.
- Download the precompiled build here
- From the archive, extract the following files to the UVR/lib_v5 application directory:
rubberband-3.1.2-gpl-executable-macos/rubberband
This process has been tested on a MacBook Pro 2021 (using M1) and a MacBook Air 2017 and is confirmed to be working on both.
See Linux Installation Instructions
These installation instructions are for Debian & Arch-based Linux systems.
- Clone the fork repository:
git clone https://github.com/kasc0206/uvrgui.git cd uvrgui - Or download from the original repository.
- Extract the downloaded file to a directory of your choice.
Use the following commands based on your system type:
For Debian-based systems (Ubuntu, Mint, etc.):
sudo apt update && sudo apt upgrade
sudo apt-get install -y ffmpeg python3-pip python3-tkFor Arch-based systems (EndeavourOS):
sudo pacman -Syu
sudo pacman -S ffmpeg python-pip tkSetting up a virtual environment (venv) ensures that the program's dependencies do not interfere with system-wide Python packages.
-
Navigate to the extracted repository directory:
cd /path/to/ultimatevocalremovergui -
Create a virtual environment:
python3 -m venv venv
-
Activate the virtual environment:
- For Debian-based and Arch-based systems:
source venv/bin/activate
- For Debian-based and Arch-based systems:
-
Install dependencies in the virtual environment:
pip install -r requirements.txt
While the virtual environment is activated, start the application:
python UVR.py-
Avoid Modifying System Files:
Previous instructions suggested deleting the/usr/lib/python3.11/EXTERNALLY-MANAGEDfile, which is dangerous and can break Python package management. Do NOT delete this file. -
Why Use Virtual Environments?
Virtual environments isolate the program's dependencies, preventing conflicts with system Python packages. More information is available here. -
Known Issues and Discussions:
If you encounter issues, refer to the GitHub Issues page for help.
- Nvidia GTX 1060 6GB is the minimum requirement for GPU conversions.
- Nvidia GPUs with at least 8GBs of V-RAM are recommended.
- AMD Radeon GPU supported is limited at this time.
- There is currently a working branch for AMD GPU users here
- This application is only compatible with 64-bit platforms.
- This application relies on the Rubber Band library for the Time-Stretch and Pitch-Shift options.
- This application relies on FFmpeg to process non-wav audio files.
- The application will automatically remember your settings when closed.
- Conversion times will significantly depend on your hardware.
- These models are computationally intensive.
- Model load times are faster.
- Importing/exporting audio files is faster.
- If FFmpeg is not installed, the application will throw an error if the user attempts to convert a non-WAV file.
- Memory allocation errors can usually be resolved by lowering the "Segment" or "Window" sizes.
There's a known issue on MacOS Sonoma where left-clicks weren't registering correctly within Tkinter applications. This was caused by a Tkinter bug on Sonoma and has since been resolved. If you still experience this issue, updating Tkinter via Homebrew should resolve it:
brew update && brew upgrade python-tkPlease be as detailed as possible when posting a new issue.
If possible, click the "Settings Button" to the left of the "Start Processing" button and click the "Error Log" button for detailed error information that can be provided to us.
This fork provides automated Windows EXE builds via GitHub Actions:
Push a version tag to trigger an automated build:
git tag v1.0.0
git push origin v1.0.0The workflow will:
- Build
UVR.exewith PyInstaller onwindows-latest - Create a ZIP archive with all runtime files
- Upload the artifact and create a GitHub Release
You can also trigger manually from the Actions tab.
docker run --rm -v "$PWD:/workspace" \
-w /workspace cdrx/pyinstaller-windows:latest \
pyinstaller UVR.spec --clean --noconfirmpip install -r requirements.txt
pip install pyinstaller
pyinstaller UVR.spec --clean --noconfirmThe output UVR.exe will be in dist/.
This fork (kasc0206/uvrgui) encompasses the following improvements over the upstream:
models/MDX_Net_Models/model_data/model_data.json— Expanded with 80+ new MDX model configs (+830/-351)models/MDX_Net_Models/model_data/model_name_mapper.json— 26 new model name mappings (+68/-66)models/VR_Models/model_data/model_data.json— Refactored VR model parameters (+272/-137)
| Category | Models |
|---|---|
| BS-Roformer | Viperx-1297, Viperx-1296, Viperx-1053 |
| Mel-Roformer | Viperx-1143 |
| MB-Roformer | Inst-v1, Inst-v2, Inst-v1-E, Duality-v1, Duality-v2, Kim, Karaoke |
| SCNet | Starrytong, Large-Starrytong, Large, XL-ZFTurbo |
| Bandit | Cinematic-Bandit-Plus, Cinematic-Bandit-Multi |
| MDX23C | InstVoc HQ 2, InstVoc D1581 |
| Other | DrumSep, Phantom-Mid, Reverb HQ, BS-Ro-Dereverb, BS-Ro-Inst-EXP |
| File | Description |
|---|---|
uvr_cli.py |
CLI tool — 10 commands (list/info/process/demucs/download-models/config/version/gui/help + --json) |
tests/ |
Test suite — 32 tests via pytest + coverage reporting |
playsound.py |
playsound3 compatibility shim |
__version__.py |
Version info with FORK_VERSION and FORK_REPO |
pyproject.toml |
Project metadata + ruff lint config |
.editorconfig |
Consistent coding style across editors |
.pre-commit-config.yaml |
Pre-commit hooks for code quality |
.gitattributes |
LF line-ending normalization |
Dockerfile |
Containerized deployment support |
gui_data/cr_text.txt |
Custom text resource file |
README_zh.md |
Full Chinese documentation |
- ruff: Zero lint errors on all custom files (F, E, W, I rulesets)
- Pylance: Reduced type errors in
UVR.pyfrom 244 → 137 (actual bugs fixed, remaining are upstream tkinter/PyTorch dynamic patterns) - Star imports: Replaced
from gui_data.constants import *with 862 explicit symbols - Bug fix:
highlightthicknestkinter typo →highlightthickness(5 occurrences) - Font tuples: Fixed ~120
font=(name, f"{size}")→font=(name, size)for Pylance compliance - Model download: Replaced
torch.hub.load_state_dict_from_urlwithcurl(500x speedup)
| Area | Tests | Status |
|---|---|---|
| CLI commands | 9 | ✅ Pass |
| Module imports | 14 | ✅ Pass |
secondary_stem mapping |
3 | ✅ Pass |
| Version & constants | 6 | ✅ Pass |
| Total | 32 | ✅ All Pass |
The Ultimate Vocal Remover GUI code is MIT-licensed.
- Please Note: For all third-party application developers who wish to use our models, please honor the MIT license by providing credit to UVR and its developers.
- ZFTurbo - Created & trained the weights for the new MDX23C models.
- DilanBoskan - Your contributions at the start of this project were essential to the success of UVR. Thank you!
- Bas Curtiz - Designed the official UVR logo, icon, banner, and splash screen.
- tsurumeso - Developed the original VR Architecture code.
- Kuielab & Woosung Choi - Developed the original MDX-Net AI code.
- Adefossez & Demucs - Developed the original Demucs AI code.
- KimberleyJSN - Advised and aided the implementation of the training scripts for MDX-Net and Demucs. Thank you!
- Hv - Helped implement chunks into the MDX-Net AI code. Thank you!
- For anyone interested in the ongoing development of Ultimate Vocal Remover GUI, please send us a pull request, and we will review it.
- This project is 100% open-source and free for anyone to use and modify as they wish.
- We only maintain the development and support for the Ultimate Vocal Remover GUI and the models provided.
- [1] Takahashi et al., "Multi-scale Multi-band DenseNets for Audio Source Separation", https://arxiv.org/pdf/1706.09588.pdf