UV Series · Foundations

What uv Is and How to Install It

If you are new to uv, the hardest part is not the installation. It is understanding what uv is replacing. uv is a Python package and project manager that can create projects, manage dependencies, run commands in the right environment, install Python versions, and run Python-based tools. Once that mental model clicks, the rest of the workflow becomes much simpler.

UV Series

1 What uv Is and How to Install It A beginner-friendly introduction to uv, what problems it solves, and how to get it running on your machine. Current article 2 Start Your First Python Project with uv init Create a real project, understand the files uv makes, and run your first program in a managed environment. Read article 3 Add Packages and Run Your Project with uv Learn the everyday commands for dependencies, environments, syncing, upgrades, and repeatable project runs. Read article 4 Add Ruff to Automate Python Code Quality Use uv to add Ruff for linting and formatting so your project catches problems and stays clean by default. Read article 5 Add ty for Type Checking and Better Feedback Add ty as a project tool so your editor and command line can catch type mistakes before runtime. Read article 6 uv vs Miniconda: Which One Fits Your Python Workflow? Use the full series to decide when uv is the better fit, when Miniconda still makes sense, and how to combine them. Read article

Goal

Install uv and understand what it is responsible for in a normal Python workflow.

Main idea

uv replaces a pile of separate habits with one consistent command line approach.

Outcome

By the end of this post, you will know what uv does, how to install it, and which commands matter first.

The beginner mental model Think of uv as the command that manages your Python project from the moment you create it until the moment you run it. Instead of separately thinking about package installation, virtual environments, lock files, and one-off tools, you start with one tool and learn its workflow in layers.

The big picture

What uv Actually Does

uv is not just a faster pip replacement. It is a broader workflow tool. In a beginner project, uv can do five jobs that are usually spread across multiple tools.

Job	Typical beginner question	uv answer
Install Python	How do I get the version of Python this project expects?	uv python install
Create a project	How do I start with the right files?	uv init
Add packages	How do I install dependencies without losing track of them?	uv add
Run code	How do I make sure my script runs in the right environment?	uv run
Run or install tools	How do I use Ruff, ty, or another CLI tool?	uvx for one-off runs or uv tool install for a persistent global install

This is why beginners often like uv once they get past the first ten minutes. The command names line up with the actions you already want to take.

Install

Install uv First, Not a Whole Tool Stack

The simplest path is to install uv and stop there until you need the next step. On macOS and Linux, the official installer is:

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

On Windows PowerShell, the official installer is:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

If you prefer a package manager, brew install uv works on Homebrew, and winget install --id=astral-sh.uv -e works on Windows with WinGet.

After installation, open a fresh terminal and run:

uv

If you see the help output, you are ready to continue.

Python versions

You Can Let uv Manage Python Too

If Python is already installed and compatible, uv will happily use it. But uv can also install Python for you, which is helpful when you want the project to feel self-contained.

uv python install
uv python install 3.12
uv python list

You do not need to memorize this immediately. The important idea is that uv can manage the interpreter as well as the project. That removes one more hidden dependency from your setup.

Do not overcomplicate the first day You do not need to learn every uv command before you start a project. A beginner can get very far with just uv init, uv add, uv run, and later uv add --dev.

First commands

The Small Set of Commands Worth Remembering First

Here is the starter set that makes uv feel practical instead of abstract:

uv init
uv add requests
uv run main.py
uv add --dev ruff
uv run ruff check .
uvx ty check

That sequence already covers the beginner lifecycle:

• create a project
• add a dependency
• run the code in the project environment
• add a development tool
• run that tool
• try another tool without permanently installing it

The rest of the series exists to make those commands feel obvious.

FAQ

Frequently Asked Questions

These are the practical questions beginners usually ask at this stage of the uv workflow.

Do I need to install Python before I install uv?

No. uv can use an existing Python installation, but it can also install Python itself when needed.

Is uv only for packages, or is it also for projects?

It is for both. That is one of the main reasons beginners find it simpler than mixing unrelated tools together.

What is the difference between uv run and uvx?

Use uv run when you want to run something inside your project environment. Use uvx when you want a quick one-off tool run in an isolated temporary environment.

Do I need to activate a virtual environment every time?

Not if you use uv run. Activation is still possible, but uv is designed so you do not have to rely on manual activation for normal project work.

Should I learn the uv pip interface first?

No. Start with the project workflow first. The uv pip interface is helpful later, especially when migrating older habits or scripts.

Conclusion

The first win with uv is not speed. It is clarity. One tool now has a name for the jobs you were already trying to do.

Next, it is time to use that clarity on a real project. We will create one with uv init, inspect the files it gives us, and run the starter code the right way.

Next in the series

Start Your First Python Project with uv init

Raell Dottin