How to install and use uv package manager in Windows?

Howard Pong Yuen Lam · AI Notes · November 1, 2026 · 6 min read

English 繁體中文 简体中文

uv is a single tool that manages both Python versions and project environments, with the same commands on Mac and Windows. This note installs it on Windows using the official command, then checks that it works.

Why uv

uv replaces several tools you would otherwise install one by one, and runs considerably faster. For details, see my VS Code + Python setup guide with uv. This note is for Windows.

Watch the walkthrough

The first video was recorded with an earlier official command. Copy the current one from “The command” section below.

Open video 1 in Google Drive · Open video 2 in Google Drive (no account needed).

The command

Open PowerShell (as shown in the video, or press Win + X), paste this line, and press Enter:

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

Three parts matter:

The script is the official one published by Astral, the company behind uv. The current instructions are at docs.astral.sh/uv/getting-started/installation.

Check the install

Close the PowerShell window and open a new one — this step matters, because the installer adds uv to your PATH and an already-open window will not see the change.

Type the two hyphens in the command below with your keyboard in English input mode. With a Chinese input method active, the two hyphens may come out as a different character, and the command will not run.

uv --version

Expected output looks like this (your version number may differ):

uv 0.13.6

If you see a version number, you are done.

Windows troubleshooting

If uv --version shows “is not recognized” even after opening a new terminal, see Windows troubleshooting in my VS Code + Python setup guide. It has step-by-step fixes, including other ways to install uv.

Use uv in a folder with your own program

Step 1: open the folder in VS Code

Choose File → Open Folder and select the folder that holds main.py and requirements.txt. Open a terminal with Terminal → New Terminal and confirm it says PowerShell.

Step 2: choose the Python version for this folder

Run these two commands, one after the other:

uv python install 3.12.10
uv python pin 3.12.10

Step 3: install the packages your program needs — choose one of the two options

Option 1

uv init
uv add -r requirements.txt

uv init creates a Python project file, pyproject.toml. TOML stands for Tom's Obvious Minimal Language — a config file format for humans (toml.io). The file keeps track of the Python version this project requires and the packages it needs.

uv add -r requirements.txt reads the package list and installs each one into the project's environment.

Option 2

uv sync

uv sync installs exactly the packages listed in the folder's uv.lock file and removes anything extra, so you get the same setup as the original project. That is why it suits a folder you downloaded from someone else, such as a GitHub project. Do not run uv init here: the folder already has a pyproject.toml, and uv will not replace it.

Step 4: run the program

uv run main.py

If you want to run a program, type uv run followed by the program's file name, such as main.py.

Steps 1 to 3 only need to be done once for each folder. When you open the folder again later, go straight to running your program.

If the packages stay the same and you only want to change the program, edit main.py and type uv run main.py again.

I think a good habit is to keep every package in requirements.txt. When you add a package, edit requirements.txt and put in the package, then save requirements.txt. Afterwards, type uv add -r requirements.txt again. This habit works whether you chose Option 1 or Option 2 in Step 3. In both cases, uv add -r requirements.txt updates the project's records and installs any package that is new, so nothing drifts out of sync.

Step 5: point VS Code at the environment

Press Ctrl + Shift + P to open the Command Palette, type Python: Select Interpreter, and pick the environment that uv created for this folder. It is labelled something like Python 3.12.10 ('.venv': venv), and its path ends in .venv\Scripts\python.exe inside your folder — for example, C:\...\folder-ai-hello-world\.venv\Scripts\python.exe. The second video above demonstrates this. Selecting it also gives you a second way to run the program: with the file open in the editor, click the play (triangle) button in the top-right corner of Visual Studio Code.