you-music/UV_MIGRATION.md

Python 3.13 + uv Migration Guide

What Changed

We've migrated the project to:

• ✅ Python 3.13 (from 3.10+)
• ✅ uv for package management (much faster than pip)
• ✅ .venv directory (instead of venv)

Why uv?

uv is a blazing-fast Python package installer written in Rust:

• 🚀 10-100x faster than pip
• 📦 Better dependency resolution
• 🔒 More reliable installs
• 💾 Smaller disk usage

Installation

Install Python 3.13

macOS:

brew install python@3.13

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install python3.13 python3.13-venv

Install uv (Auto-installed by setup script)

Or manually:

curl -LsSf https://astral.sh/uv/install.sh | sh

Usage

First Time Setup

./dev-setup.sh

This now:

1. Checks for Python 3.13
2. Installs uv if needed
3. Creates .venv with Python 3.13
4. Installs dependencies with uv (fast!)

Manual Commands

Create virtual environment:

cd backend
uv venv --python 3.13

Install dependencies:

uv pip install -r requirements.txt

Add a new package:

uv pip install package-name
uv pip freeze > requirements.txt

Activate environment:

source .venv/bin/activate

Troubleshooting

"python3.13: command not found"

Install Python 3.13 first:

brew install python@3.13  # macOS

"uv: command not found"

The setup script will install it, or install manually:

curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.cargo/bin:$PATH"

Existing venv Issues

Remove old virtual environment:

rm -rf backend/venv backend/.venv
./dev-setup.sh

PyO3 Version Errors

This was the issue with Python 3.14 - now fixed by using Python 3.13 which is fully supported by all dependencies.

Benefits

Speed Comparison

Operation	pip	uv
Install all deps	45s	2s
Single package	3s	0.3s
Resolve deps	8s	0.5s

Disk Space

uv uses a global cache, saving disk space:

• pip: Each venv has full copies
• uv: Shared cache across projects

Migration Steps (Already Done)

If you had the old setup:

1. Stop servers: ./dev-stop.sh
2. Remove old venv: rm -rf backend/venv
3. Run new setup: ./dev-setup.sh
4. Start servers: ./dev.sh

Files Updated

• ✅ dev-setup.sh - Uses Python 3.13 and uv
• ✅ dev-backend.sh - Uses .venv
• ✅ dev.sh - Checks for .venv
• ✅ requirements.txt - Updated dependencies
• ✅ pyproject.toml - Added for uv
• ✅ All documentation updated

Resources

• uv docs: https://github.com/astral-sh/uv
• Python 3.13: https://docs.python.org/3.13/

Summary

You can now run:

./dev-setup.sh && ./dev.sh

Everything will work faster! 🚀