UVR5 UI

This project is based on python-audio-separator (a CLI version of UVR5). This project was originally created for the AI ​​HUB community.

You can also try it on HuggingFace Spaces running with Zero GPU (A100)!

Docs / Troubleshooting

Features:

• User Friendly Interface
• All VR Arch Models
• All MDX-NET Models
• Demucs v4 Models
• MDX23C Models
• Mel-Band Roformer Models
• BS Roformer Models
• Music Source Separation Models
• VIP Models
• Separation of an audio/video from all sites supported by yt_dlp. Check the complete list here.
• Batch Separation
• Ensembles: combine 2 to 6 models of any architecture with 11 algorithms, curated presets or your own
• Native FP16, torch.compile and chunked processing for long audio (Settings > Performance)
• Custom output file names and a one-click download of all the stems
• Available in multiple languages
• Colab/Kaggle/Lightning.ai support
• Windows/Linux support

Requirements

Hardware Requirements:

• Nvidia Series 2000 (RTX) or higher.
• At least 10Gb of disk space.

[!NOTE]
Older NVIDIA GPUs will be very slow. CPU will be insanely slow. If you don't meet the hardware requirements use our Colab/Kaggle/Lightning.ai/Hugging Face.

Prerequisites:

• Git. You can download Git here.
• FFmpeg. You can download FFmpeg here or you can use my automated installation script (for Windows).
• For linux users, run this command on an terminal: (Debian and Ubuntu users): sudo apt install ffmpeg git build-essential (For Arch linux users): sudo pacman -S ffmpeg git base-devel (For Fedora users): sudo dnf install ffmpeg git gcc gcc-c++ (Some distributions already come with Git, FFmpeg and a C compiler preinstalled so this step may be optional. The compiler is needed to build one of the dependencies during installation.)

[!IMPORTANT]
FFmpeg has to be added to the PATH. (only needed on Windows)

Getting Started

Clone the repository (git needed) or download the source code of the latest release here

git clone https://github.com/Eddycrack864/UVR5-UI.git

Then continue with the steps described below

1. Installation

Run the installation script based on your operating system:

• Windows: Double-click UVR5-UI-installer.bat (DONT RUN AS ADMINISTRATOR 🚧).
• Linux: Run UVR5-UI-installer.sh with chmod +x UVR5-UI-installer.sh and ./UVR5-UI-installer.sh.

2. Running UVR5 UI

Start UVR5 UI using:

• Windows: Double-click run-UVR5-UI.bat.
• Linux: Run run-UVR5-UI.sh with chmod +x run-UVR5-UI.sh and ./run-UVR5-UI.sh.

Extra options can be added to the run scripts (or to python app.py):

Option	Description
--share	Create a temporary public Gradio link
--listen-port 8080	Use another port (default: 9999)
--server-name 0.0.0.0	Make the UI reachable from other devices on your network
--open	Open the UI in your browser (the run scripts already do this)
--run-history	Keep a history of your separations in the browser (off by default)

Example: run-UVR5-UI.bat --share --listen-port 8080

3. Update UVR5 UI (If you want/need it)

Update UVR5 UI using (git needed):

• Windows: Double-click UVR5-UI-updater.bat.
• Linux: Run UVR5-UI-updater.sh with chmod +x UVR5-UI-updater.sh and ./UVR5-UI-updater.sh.

Your preferences (language, theme, saved separation settings) live in the user_data/ folder and your models in models/; updating never touches them.

UVR5 UI runs on Python 3.13. If your installation is older (Python 3.10), the updater offers to rebuild the Python environment automatically. It downloads about 3 GB and needs about 6 GB of free disk space while it runs; if anything fails, your previous environment is restored.

If you find an error when installing or running the program please consult this troubleshooting file first, if your error is not described there please create an issue

4. Debug (If you want/need it)

Check the status of audio-separator core:

• Windows: Double-click info/status-checker.bat.
• Linux: Run info/status-checker.sh with chmod +x info/status-checker.sh and ./info/status-checker.sh.

Development

The app is a Python package, uvr5_ui/, organised in layers:

Path	What lives there
app.py	Thin launcher (python app.py [options], or python -m uvr5_ui)
uvr5_ui/core/	Separation, model catalog, downloads, leaderboard. No Gradio imports, testable on its own
uvr5_ui/core/separation/specs.py	One declarative ArchSpec per architecture (parameters, ranges, defaults). All separation tabs and the separation service are generated from it
uvr5_ui/ui/	Gradio layer: one module per tab in ui/tabs/, plus shared widgets and handler adapters
uvr5_ui/config/	App config (assets/config.default.json merged with user_data/config.json) and separation presets
assets/	Data only: model catalog (models.json), default settings, translations, themes

Common tasks:

# Install the test tools (once) and run the tests
env/python.exe -m pip install -r requirements-dev.txt   # Linux: env/bin/python
env/python.exe -m pytest

# Check that every translatable string exists in en_US.json and in every other language
env/python.exe tools/i18n_scan.py --check --langs

# Model catalog (needs internet)
env/python.exe tools/check_model_links.py          # are all download links working? which models are not on the Hugging Face mirror yet?
env/python.exe tools/sync_models.py --write        # add the models audio-separator supports and fill the sources that now work
env/python.exe -m pytest --network                 # also run the tests that check the links and the catalog online

After updating audio-separator, run tools/sync_models.py --write: the catalog must list every model it supports (tests/test_catalog.py checks its bundled list offline). New models only get a Hugging Face source once all their files are on the mirror; run the sync again after uploading them.

• Add a model: add an entry to assets/models.json (id, arch, filename, download sources). It appears in its tab automatically.
• Add a parameter: add a ParamSpec to its architecture in uvr5_ui/core/separation/specs.py and its default to assets/default_settings.json.
• Translations: the English text passed to i18n("...") is the key in every language file, so changing it breaks existing translations. A new string must be added to all the files in assets/i18n/languages/ (named like xx_XX.json); tests/test_i18n_scan.py fails if a language is missing one.

Precompiled Version

The precompiled version already includes the Python environment, so there is nothing to install: download, extract and run.

1. Get the precompiled version for your PC (the latest one is also linked in each release):

   • Windows (.zip)
   • Linux (.tar.gz, needs glibc 2.35 or newer: Ubuntu 22.04, Debian 12, Fedora 36 or later)

2. Extract it, it contains a UVR5-UI folder:

   • Windows: right click > "Extract All..." (or "Extract here" with 7-Zip/WinRAR).
   • Linux: tar -xzf UVR5-UI-vX.X.X-linux.tar.gz

3. Run run-UVR5-UI.bat (Windows) or ./run-UVR5-UI.sh (Linux). You can now use all the features of the normal installation.

FFmpeg is still needed (see the prerequisites).

[!NOTE]
Still, to update UVR5 UI you need to install Git.

There is also a pre-compiled version primarily for Chinese users developed by jian27, get it here. Just 2.6 GB!

Docker Instance

A more technical level is required for this type of use. You can use this Jupyter notebook to initialize UVR5 on virtual machines with GPU. This will install the entire UVR5 from the main branch of GitHub.

Requirements/Recommendations

• Use the docker image >= ubuntu/ubuntu:20.04
• At least 20 GB of storage minimum. (Add more space for your models/training)
• Use Jupyter >= 7.3.1
• Configure port forwarding 9999 (UVR5-UI GUI)
• Install necessary drivers to use the GPU
• Install a C compiler (apt install build-essential), needed to build one of the dependencies

You can get the notebook here: Jupyter Notebook by iroaK

Contributions

If you want to participate and help me with this project feel free to create an issue if something goes wrong or make a pull request to improve this project.

Any type of contribution is welcome 💖

If you like this project you can star this repository. I will appreciate a lot 💖💖💖

You can donate to the original UVR5 project here:

TO-DO

• Add more models
• Add more output formats

Credits

• python-audio-separator by beveradb.
• Special thanks to Ilaria for hosting this space and help 💖
• Thanks to Mikus for the help with the code.
• Thanks to Nick088 for the help to fix roformers.
• Thanks to yt_dlp devs.
• Separation by link source code and improvements by AsukaDev.
• Thanks to ArisDev for porting UVR5 UI to Kaggle and improvements.