UV Project Setup Guide

🚀 UV Project Setup Guide

A Clear Path from Any Python Project to Reproducible Environments

🌟 Why This Guide Matters

In modern Python development, the biggest challenge is not writing code —
it is making code reproducible across machines and environments.

This guide introduces a simple rule:

If you understand the difference between a UV project and a non-UV project,
you can start any Python project in seconds.

🧩 1. What Is a UV Project?

A UV project is a Python project managed by uv and defined by two key files:

🔑 Core Files

pyproject.toml → Project definition (dependencies, metadata)
uv.lock → Exact locked dependency versions (reproducibility)

📦 What Makes It Special?

When these files exist, you do NOT need manual setup.

You simply run:

uv sync

And uv will:

Create .venv/ automatically
Install all dependencies
Reproduce the exact environment

🧠 Key Insight

A UV project is self-describing.
It contains everything needed to rebuild itself.

⚡ 2. Working with UV Projects

📥 Case 1: From GitHub

git clone https://github.com/username/project.git
cd project
uv sync

💻 Case 2: From Another Computer

Do NOT copy:

.venv/
cache files

Just copy:

source code
pyproject.toml
uv.lock

cd project
uv sync

📁 Case 3: From Local Folder

If pyproject.toml exists:

uv sync

⚡ Optional: Template Initialization

uv init --from-template <repo-url>

🔄 3. Non-UV Projects (Legacy Python)

Typical signs:

requirements.txt
Pipfile
poetry.lock
Missing pyproject.toml

📄 Case 1: requirements.txt

uv init
uv add -r requirements.txt

📦 Case 2: Pipenv

uv init
uv add package1 package2

📚 Case 3: Poetry

uv init
uv add <dependencies>

⚙️ 4. Essential Commands

uv run python main.py
uv add requests
uv add pytest --dev
uv remove package
uv sync --upgrade

🛠️ 5. Troubleshooting

uv cache clean
uv sync --reinstall

🎯 6. Best Practices

Always commit:

pyproject.toml
uv.lock

Never commit:

.venv/
__pycache__/

🎉 Final Takeaway

👉 Is this a UV project?

YES → uv sync
NO → uv init + import dependencies

📚 Deepsim Press Companion Note

This guide helps readers:

Reproduce environments instantly\
Avoid dependency conflicts\
Focus on learning instead of setup

Happy coding with UV 🚀

Found this useful? Share it