How to install and use uv package manager on a Mac?
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 a Mac 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 Mac. For Windows, see the Windows version of this note.
Watch the walkthrough
Open in Google Drive (no account needed).
The command
Open Terminal (press Cmd + Space, type Terminal, and
press Enter), paste this line, and press Enter:
curl -LsSf https://astral.sh/uv/install.sh | sh
Three parts matter:
curldownloads the installer script.-LsSfkeeps the download quiet, but still shows an error if something fails.- The
| shat the end runs that script.
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 Terminal window and open a new one — this step matters, because
the installer adds uv to your PATH in your shell profile, 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.
Mac troubleshooting
If uv --version shows command not found even after opening a new
terminal, install it with Homebrew instead: brew install uv. My
VS Code + Python setup guide has more on how 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.
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. In Option 2, do not
run uv init: 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 Cmd + Shift + P to open the Command Palette, type
Python: Select Interpreter, and pick the environment that uv created for this
folder. If the folder is named folder-ai-hello-world, the list shows an entry
carrying that name. Selecting it also gives you a second way to run the program: with the file
open in the editor, click the triangle button in the top-right corner of Visual Studio Code.