uv for Python: Install and Manage Python Versions Easily

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 -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS/Linux install:

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:

Python + venv + pip + requirements.txt

uv gives you a faster modern workflow:

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 -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Close and reopen PowerShell.

Check:

uv --version
where.exe uv

Alternative with WinGet:

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:

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

Restart Terminal or reload your shell:

source ~/.zshrc

Check:

uv --version
which uv
echo $PATH

If you use Homebrew:

brew install uv

4. Install uv On Linux

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

Then:

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:

uv python list

Install the latest supported Python:

uv python install

Install a specific version:

uv python install 3.14
uv python install 3.13

Show installed versions:

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

uv init hello-uv
cd hello-uv

Run the generated project:

uv run hello.py

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

7. Add Packages

uv add pandas matplotlib

uv updates:

pyproject.toml
uv.lock

Run Python inside the project:

uv run python

Test a package:

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

8. Run A Script

Create analyze.py:

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:

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:

uv pip install -r requirements.txt

Inside an existing venv:

Windows:

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

macOS:

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

10. Common uv Commands

11. Files In A uv Project

Common files:

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

Commit:

pyproject.toml
uv.lock
README.md

Do not commit:

.venv/

12. Windows And macOS PATH Fixes

Windows:

uv --version
where.exe uv

macOS:

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:

brew update
brew upgrade uv

If you installed uv with WinGet:

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:

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:

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.

Next in this series: Choosing Between VS Code and PyCharm for Python Development →