# Getting Started with uv for Python: Installation and Project Setup
URL: https://madhudadi.in/blog/posts/uv-for-python-install-and-manage-python-versions-easily
Published: 2026-06-10
Tags: python, setup
Read time: 44 min
Difficulty: beginner
> Learn uv, the modern Python package and project manager: install uv, create projects, manage Python versions, add packages, run scripts, and replace common pip workflows.# uv for Python: Install, Manage Python Versions, Create Environments, and Run Projects

## Quick Answer

`uv` is a modern Python tool from Astral. It can install Python versions, create project environments, add packages, run scripts, and sync dependencies.

Windows install:

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

macOS/Linux install:

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

Last verified: June 9, 2026.

## Official Links

- uv docs: https://docs.astral.sh/uv/
- uv installation: https://docs.astral.sh/uv/getting-started/installation/
- uv Python management: https://docs.astral.sh/uv/guides/install-python/
- uv GitHub releases: https://github.com/astral-sh/uv/releases
- Homebrew: https://brew.sh/

## What You Will Learn

By the end, you should be able to:

- install uv on Windows and macOS
- fix uv PATH issues
- install Python with uv
- create a uv project
- add packages
- run scripts
- understand `uv pip`
- know when uv is better than plain `venv` and `pip`

## 1. Why Learn uv?

Traditional beginner setup uses:

```text
Python + venv + pip + requirements.txt
```

uv gives you a faster modern workflow:

```text
uv + pyproject.toml + uv.lock + .venv
```

You should still understand `venv` and `pip`, because uv builds on the same Python packaging ideas.

## 2. Install uv On Windows

Open PowerShell.

Official installer:

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

Close and reopen PowerShell.

Check:

```powershell
uv --version
where.exe uv
```

Alternative with WinGet:

```powershell
winget install --id=astral-sh.uv -e
```

If `uv` is not recognized after install, restart PowerShell. If it still fails, the installer path was not added to PATH.

## 3. Install uv On macOS

Official installer:

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

Restart Terminal or reload your shell:

```bash
source ~/.zshrc
```

Check:

```bash
uv --version
which uv
echo $PATH
```

If you use Homebrew:

```bash
brew install uv
```

## 4. Install uv On Linux

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

Then:

```bash
uv --version
which uv
```

If the command is missing, restart the shell or add uv's install directory to PATH as instructed by the installer.

## 5. Install Python With uv

List available Python versions:

```bash
uv python list
```

Install the latest supported Python:

```bash
uv python install
```

Install a specific version:

```bash
uv python install 3.14
uv python install 3.13
```

Show installed versions:

```bash
uv python list --only-installed
```

uv uses standalone Python builds. This is useful when your operating system Python is old or managed by the OS.

## 6. Create A New uv Project

```bash
uv init hello-uv
cd hello-uv
```

Run the generated project:

```bash
uv run hello.py
```

If uv created a different starter file name, run that file instead.

## 7. Add Packages

```bash
uv add pandas matplotlib
```

uv updates:

```text
pyproject.toml
uv.lock
```

Run Python inside the project:

```bash
uv run python
```

Test a package:

```bash
uv run python -c "import pandas as pd; print(pd.__version__)"
```

## 8. Run A Script

Create `analyze.py`:

```python
import pandas as pd

data = pd.DataFrame({
    "topic": ["setup", "venv", "uv"],
    "hours": [2, 3, 2],
})

print(data)
print("Total hours:", data["hours"].sum())
```

Run it:

```bash
uv run analyze.py
```

`uv run` makes sure the project environment is used.

## 9. Use uv With requirements.txt

If an older project has `requirements.txt`, use:

```bash
uv pip install -r requirements.txt
```

Inside an existing venv:

Windows:

```powershell
py -m venv .venv
.\.venv\Scripts\Activate.ps1
uv pip install -r requirements.txt
```

macOS:

```bash
python3 -m venv .venv
source .venv/bin/activate
uv pip install -r requirements.txt
```

## 10. Common uv Commands

| Command | Purpose |
| --- | --- |
| `uv --version` | Check uv |
| `uv python list` | Show Python versions |
| `uv python install 3.14` | Install Python 3.14 |
| `uv init my-project` | Create a project |
| `uv add requests` | Add dependency |
| `uv remove requests` | Remove dependency |
| `uv run python script.py` | Run inside project environment |
| `uv sync` | Install dependencies from lockfile |

## 11. Files In A uv Project

Common files:

```text
my-project/
  pyproject.toml
  uv.lock
  README.md
  .venv/
```

Commit:

```text
pyproject.toml
uv.lock
README.md
```

Do not commit:

```text
.venv/
```

## 12. Windows And macOS PATH Fixes

Windows:

```powershell
uv --version
where.exe uv
```

macOS:

```bash
uv --version
which uv
echo $PATH
```

If uv is not found:

1. Close and reopen the terminal.
2. Check the install message for the path it added.
3. Add only that path to PATH.
4. Restart the terminal again.

## 13. Update Or Uninstall uv

If you installed uv with the official standalone installer, check the latest command in the uv installation docs before updating.

If you installed uv with Homebrew:

```bash
brew update
brew upgrade uv
```

If you installed uv with WinGet:

```powershell
winget upgrade --id=astral-sh.uv -e
```

To remove uv, use the same tool you used to install it:

- Homebrew: `brew uninstall uv`
- WinGet: `winget uninstall --id=astral-sh.uv -e`
- official installer: follow the uninstall instructions printed by the installer or uv docs

## 14. When Not To Use uv

Avoid uv if:

- your company requires a different tool
- your course specifically teaches `venv` and `pip`
- you are debugging a problem where fewer tools make learning easier

Otherwise, uv is a strong modern default for new Python projects.

## FAQ

### Does uv replace pip?

For many project workflows, yes. But pip is still fundamental, widely documented, and worth learning.

### Does uv replace venv?

uv can create and manage environments for you, but the environment concept is still the same.

### Should beginners learn uv first?

Learn basic Python, `venv`, and pip first. Then use uv for faster day-to-day project work.

### Can uv install Python on macOS and Windows?

Yes. `uv python install` can install Python builds without changing your system Python.

## Final Checklist

Windows:

```powershell
uv --version
where.exe uv
uv python list
uv python install 3.14
uv init hello-uv
cd hello-uv
uv add requests
uv run python -c "import requests; print(requests.__version__)"
```

macOS:

```bash
uv --version
which uv
uv python list
uv python install 3.14
uv init hello-uv
cd hello-uv
uv add requests
uv run python -c "import requests; print(requests.__version__)"
```

If these work, uv is ready for real projects.