How to install and use uv package manager on a Mac?

Howard Pong Yuen Lam · AI Notes · November 1, 2026 · 5 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 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:

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

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.