UVR with UV Environment - Smart AI Audio Separation

About This UV Environment Version

This is a UV-powered distribution of Ultimate Vocal Remover GUI, featuring intelligent dependency management and automatic GPU optimization. Built with modern Python tooling for effortless installation and superior performance.

Why UV Environment?

• ⚡ Lightning-fast setup: One command installation with automatic dependency resolution
• 🧠 Smart GPU detection: Auto-configures CUDA/PyTorch for optimal performance
• 🛡️ Conflict-free: Isolated environment prevents system package conflicts
• 🔄 Future-proof: Automatically handles new CUDA versions and dependencies

✨ UV Environment Advantages

• ⚡ Zero-Config Setup: uv run setup_and_run.py - that's it!
• 🧠 Intelligent CUDA Matching: Auto-detects your GPU and installs compatible PyTorch
• 🛡️ Dependency Isolation: No more version conflicts or system pollution
• 🚀 Performance Optimized: UV's parallel dependency resolution = faster installs
• 🔄 Reproducible Builds: Lock files ensure consistent environments across machines
• 🎯 Future-Ready: Handles upcoming CUDA 13.0+ and PyTorch versions automatically

🚀 Quick Start with UV

One-Command Setup & Run

# Complete setup and launch (recommended for first-time users)
uv run setup_and_run.py

Daily Usage (After Setup)

# Quick launch
uv run UVR.py

# Or use the project script
uv run uvr

Advanced Usage

# Verify/update GPU support + launch
uv run smart_pytorch_installer.py && uv run UVR.py

# Full sync + GPU check + launch (for troubleshooting)
uv sync && uv run smart_pytorch_installer.py && uv run UVR.py

That's it! UV handles all the complexity behind the scenes.

🎮 Smart GPU Support

The UV environment automatically handles GPU optimization:

• Auto-Detection: Detects your NVIDIA GPU and CUDA version
• Smart PyTorch: Installs the optimal PyTorch version for your hardware
• Fallback Protection: Gracefully falls back to CPU if GPU setup fails
• Performance: 5-10x faster processing with compatible GPUs (GTX 1060 6GB+)

📦 Alternative Installation (Manual)

If you prefer manual control over the UV environment:

Prerequisites

• Python 3.10+
• UV package manager (pip install uv)

Manual Steps

# 1. Clone this repository
git clone https://github.com/Marksooxx/UV_UVR

# 2. Create UV environment and install
uv venv --python 3.11
uv sync
uv run smart_pytorch_installer.py
uv run UVR.py

# 3. Alternative: Traditional pip (not recommended)
python -m venv venv
# Windows: venv\Scripts\activate
# Linux/macOS: source venv/bin/activate
pip install -r requirements.txt
python UVR.py

Note: The automated uv run setup_and_run.py is still recommended for most users.

🧠 Why UV Environment?

Traditional Installation Pain Points

❌ Manual CUDA/PyTorch version matching ❌ Dependency conflicts with system packages ❌ Complex virtual environment setup ❌ Slow pip dependency resolution ❌ Inconsistent environments across systems

UV Environment Solutions

✅ Automatic CUDA Detection - Matches your GPU perfectly ✅ Isolated Dependencies - Zero conflicts with system packages ✅ Lightning Setup - UV's Rust-based resolver is 10-100x faster ✅ Reproducible Builds - Lock files ensure consistency ✅ Future-Proof - Handles new CUDA versions automatically

CUDA Support Matrix

CUDA Version	Auto-Selected PyTorch	Status
11.6-11.8	cu118	✅ Perfect
12.0-12.3	cu121	✅ Perfect
12.4-12.9	cu124	✅ Perfect
13.0+	cu124 + smart warnings	✅ Future-ready
No GPU	CPU version	✅ Auto fallback

✅ Verification

Quick verification script:

uv run python -c "
import torch
print('PyTorch:', torch.__version__)
print('CUDA Available:', torch.cuda.is_available())
if torch.cuda.is_available():
    print('GPU:', torch.cuda.get_device_name(0))
print('✅ Installation successful!' if torch.cuda.is_available() else '⚠️ CPU mode')
"

🔧 Troubleshooting

Common Issues

Issue: "CUDA not available"

# Re-run smart installer
uv run smart_pytorch_installer.py

Issue: "Installation failed"

# Clean reinstall
rm -rf .venv __pycache__
uv run setup_and_run.py

Issue: "GPU memory error"

• Lower batch size in settings
• Close other GPU applications
• Use smaller audio files for testing

System Requirements

• Windows: Windows 10+
• macOS: macOS Big Sur+
• Linux: Ubuntu 20.04+
• GPU: NVIDIA GTX 1060 6GB+ (recommended)

📋 Technical Stack

• Deep Learning: PyTorch 2.6.0+ (CUDA version)
• Audio Processing: librosa, soundfile, audioread
• GPU Acceleration: ONNX Runtime GPU, TensorRT
• User Interface: tkinter with modern themes
• Package Management: uv (recommended), pip

📄 License

Ultimate Vocal Remover GUI is MIT-licensed.

Note: Third-party developers using our models must provide proper attribution to UVR and its developers.

🙏 Credits

• ZFTurbo - MDX23C models
• DilanBoskan - Early contributions
• Bas Curtiz - Official UVR logo and design
• tsurumeso - Original VR Architecture
• Kuielab & Woosung Choi - Original MDX-Net AI
• Adefossez & Demucs - Original Demucs AI