How to install and use uv package manager in Windows?
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
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:
irmis shorthand forInvoke-RestMethod— it downloads the installer script.iexis shorthand forInvoke-Expression— it runs that script.-ExecutionPolicy ByPasslets this one command run a downloaded script even if your machine normally blocks them. It applies to that command only; it does not change your system-wide policy.
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
- The first command downloads Python 3.12.10 onto your computer. You do this once; other projects can reuse the Python version later.
- The second command tells this folder to use Python 3.12.10, and saves that choice in a small file called
.python-version. Anyone — or any program — who opens this folder later will use the same version.
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.