🚀 uv – Modern Python Package & Environment Manager

uv is a fast, modern, and opinionated Python package manager designed to replace pip, virtualenv, pip-tools, and partially even poetry.

It is written in Rust, which means it is:

• Extremely fast
• Deterministic
• Reproducible by default

---

❓ Why uv?

Problems with the traditional Python workflow

• Manual virtual environment creation and activation
• Slow dependency resolution
• requirements.txt does not guarantee reproducibility
• Different environments across machines
• Global installation of tools like ruff, black, etc.

What uv fixes

• ⚡ Very fast dependency resolution (Rust-based)
• 🧠 Automatic virtual environment management
• 🔒 Reproducible builds using pyproject.toml & uv.lock

---

📦 Installation

Official documentation:
https://docs.astral.sh/uv/getting-started/installation/

---

🧱 🟠 Initialize uv in the new or current existing project

(Automatically Creates Virtual Environment — No Manual Setup)

uv automatically creates and manages the .venv for you.
You never need to activate or configure it manually.

🔹 SYNTAX

To initialze uv in a new project(with default available python version)

uv init app_name

OR

To initialze uv in a new project(with specific/particular python version)

uv init app_name -p <python-version>

OR

To Initialize uv in the existing project(with specific python version)

uv init -p <python-version>

OR

To Initialize uv in the existing project(without specific python version)

uv init .

🔹 EXAMPLES

➡️ Default project structure

uv init new_app --app

OR

uv init -p 3.14.2

OR

uv init -p 3.14.2 .

OR

uv init --python 3.14.2 .

➡️ Build app as a Python package

uv init new_app --lib

---

🟢 Install partiuclar python version that you need inside uv environment

🔹 Syntax

uv python install <version>

🔹 Example

uv python install 3.13.3

To list the installed python versions in uv environment

🔹 EXAMPLES:

To check all the installed(downloaded) python in the uv

uv python list

To check the current running version of python inside uv

uv run py -V

OR

uv run python --version

To uninstall :-

🔹 Example

uv python uninstall 3.13.3

---

Creating virtual environment (.venv)

There are two ways to create .venv:-

One Way:- Creating .venv without any dependencies/packages installed.

    uv venv

Another Way :- Creating .venv automatically while adding/installing dependencies/packages.

Syntax:-

    uv add package_name

Example

    uv add "fastapi[standard]"
    uv add pydantic
    uv add sqlalchemy
    v add psycopg[binary]

---

📁 uv directory structure

---

🔁 Initializing uv in cloned remote project

🔄 Syncing Environment

Use this when: - you have to synchronize .venv (or create a .venv) for a project.

How "uv sync" command works?

• It looks for the pyproject.toml file and then creates uv.lock file.
• Now, using uv.lock file it creates .venv directory.
• It is mostly used command.

uv sync --> searches pyproject.toml --> creates uv.lock ---> creates .venv (install all dependencies)

🔹 Command

uv sync

🔒 Locking / Freezing Environment

How "uv lock" command works?

• It looks for the pyproject.toml file and then creates uv.lock file, but doesn't creates .venv (no dependencies installation).
• It is rarely used command.

uv lock --> searches pyproject.toml --> creates uv.lock (listing all minor dependencies without installation)

---

♻️ Migrate existing pip managed project to uv managed

If you already have a project created using pip and want to move it to uv:

✅ No need to create a new project

✅ No need to migrate manually

🪜 Step 1: Initialize uv

uv init

🪜 Step 2: Install all packages from requirements.txt

uv add -r requirements.txt

---

💻 Run project using uv

There are two ways to run project:-

💡 One Way:- Use uv run command each time.

🔹 Syntax

uv run project_file.py

🔹 Example 1

uv run main.py 

If you are using django and you want to run server.

🔹 Example 2

uv run python manage.py runserver 

🔀 Another Way :- Activate .venv manually and run command without uv

Activate virtual environment

For Windows:

.venv\Scripts\activate

For Linux:

source .venv/bin/activate

Run project file

🔹 Example 1

python main.py 

If you are using django and you want to run server.

🔹 Example 2

python manage.py runserver 

🏁 Your existing project is now fully managed by uv.

---

➕ Add a Package Using uv

🔹 Syntax

uv add package_name

OR

uv add package_name1 package_name2 ... 

🔹 Example

uv add flask

OR

uv add pandas flask django

---

➖ Remove Packages/Dependencies

Remove specific packages

🔹 Syntax

uv remove package_name

🔹 Example

uv remove flask

Remove all packages

Step 1 : Manually remove all dependencies from pyproject.toml

[project]
name = "new-app"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13.3"
dependencies = []                                       #empty dependencies list

Step 2 : Regenerates uv.lock with zero runtime dependencies.

uv lock

Step 3: Sync the environment

uv sync

This sync everything.

---

🌳 Visualize Dependency Tree

See exactly which package depends on what:

uv tree

Helpful when debugging dependency conflicts.

---

®️ Running Tools with uvx

❓What is uvx? Why it is required?

uvx is a tool runner, similar to:

• pipx
• npx
  

It's job :

• Run CLI applications (like streamlit, black, ruff, pytest)
• Install them temporarily or globally

Use uvx when:

• You’re running a tool
• The tool has a CLI

uvx does one core thing:

• Run a Python CLI tool via its entry point, in an isolated environment.

There are two different method to run tools:-

🔒 Installs the tool into a persistent tool environment managed by uv

What it actually means :-

• Installs the tool into uv-managed tool environment, in a global location under your user home directory.

~/.local/share/uv/

• NOT your project .venv
• Creates a stable CLI command on your PATH

Consequences :-

• Tool is installed once
• Reused across projects

🔹 Syntax

uv tool install tool_name

🔹 Example Command

uv tool install ruff 

Installs ruff into uv’s tool environment and exposes ruff on your PATH.

🔹Run the tool

ruff check

---

BONUS / TIPS

📌 What uv python pin actually does?

• Creates/updates .python-version
• Tells uv which interpreter to run commands with.

🔹 Syntax

uv python pin python_version

🔹 Example

uv python pin 3.13.3

✅ Summary

• Automatic virtual environments
• Clean dependency management
• Reproducible builds via uv.lock
• Temporary tooling without system pollution
• Simple, fast, and reliable Python workflow

WALLAAHH !!