VS Code + Python Setup Guide with uv Package Manager
https://docs.astral.sh/uv/ is a single tool that manages both Python versions and project environments, with identical commands on Mac and Windows. It removes the “which Python is my terminal finding” problem, and does not require users to manually manage a virtual environment.
Setup to install uv
-
If we install uv using the official standalone installer instead of
pip install uv, the installer doesn't depend on any pre-existing Python/pip (Python's package installer) setup. So, it works the same regardless of what's already on the machine. It also handles a technical setup step for us automatically — normally our computer needs to be told where to find theuvprogram (PATH) before we can typeuvcommands in the terminal; this installer takes care of that on its own, so we won't need to configure anything.As of Aug 2026, the following commands can be found via the install button on https://astral.sh/uv:
Mac:
curl -LsSf https://astral.sh/uv/install.sh | shWindows (PowerShell):
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"⚠️ Close the terminal and open a brand new one right after installing, before typing any
uvcommand. The installer sets up the “where to finduv” (PATH) step mentioned above, but the terminal we already have open doesn't know about that change yet — it only notices it the next time we start a new terminal. So if we typeuv --versionin that same terminal right after installing, it will say “command not found” even though the install actually worked. This is the single most common hiccup users hit with this step.💡 Using Windows and still stuck? If
uv --versionstill shows “is not recognized” even after opening a new terminal, see Windows troubleshooting below. It has step-by-step fixes, including other ways to install uv when the command above doesn't work on our Windows computer.Here's what a successful install looks like, for reference (the username and version number will differ on your machine):
downloading uv 0.12.9 (x86_64-pc-windows-msvc)
installing to C:\Users\Howard\.local\bin
uv.exe
uvx.exe
uvw.exe
everything's installed!
To add C:\Users\Howard\.local\bin to your PATH, either restart your shell or run:
set Path=C:\Users\Howard\.local\bin;%Path% (cmd)
$env:Path = "C:\Users\Howard\.local\bin;$env:Path" (powershell)“everything's installed!” confirms the install itself succeeded. The PATH note right after it is the installer describing the exact hiccup in the callout above — it's telling us the new
uvcommand won't be found in this terminal until we either start a fresh one, or manually run one of the two commands shown for our shell. Simplest is to just close this terminal and open a new one, then continue to step 2 below. -
Confirm it worked (in the new terminal):
uv --version -
Install a Python version:
uv python install 3.12.10 -
Pin it for the class project:
uv python pin 3.12.10Note:
pinonly sets the Python version for the folder we run it in, and any subfolders under it. Run it from our top-level projects folder so every new project automatically gets 3.12.10 too. -
Confirm which Python versions uv has installed:
uv python list --only-installed
Setup to run a Python (.py) program
-
Initialize the project — run this once per folder:
uv initTip: Create a new folder for each project before running this command.
uv inituses our current folder's name as the project's name, so keeping one project per folder avoids mix-ups and keeps things organized.Tip: If the current folder happens to sit under another folder (a parent folder) that is already a uv project, run
uv init --no-workspaceinstead. Otherwise,uv initmay treat the current folder as a member of the parent folder's project workspace. In other words,--no-workspacetells uv that we do not want to use the parent folder's workspace. Since uv automatically shares downloaded packages across all our projects behind the scenes, without duplicating them on disk, there's no need to nest projects inside each other to save space. So it's simplest to keep every project folder on its own, rather than inside another folder that is itself a uv project or workspace. -
Add packages as needed — run this each time you need one:
uv add matplotlib(or
uv add -r requirements.txtto install from a requirements file) -
Run the script:
uv run main.py
That's it — the same two commands (uv add, uv run) work identically on every user's machine, regardless of Operating System (OS) or whatever Python setup was already there.
pyproject.toml (created automatically by uv init) is the project's settings file — a simple text file that lists the project's name and the packages it needs. When we type uv run main.py, uv finds pyproject.toml in the current folder, locates/creates the matching Virtual Environment .venv, and executes the script inside that environment directly. This command is identical on Mac and Windows, so there is no OS branching for macOS or Windows (no source .venv/bin/activate vs .venv\Scripts\activate). Learn more about the .toml format at What is TOML? — Tom's Obvious Minimal Language Explained.
VS Code's ▶ Run/Debug button: The .venv folder is created automatically the first time we run uv add or uv run — just running uv init by itself doesn't create it yet. Once .venv exists, VS Code's Python extension auto-detects it in Select Interpreter. Clicking ▶ Run or Debug then runs our code using that environment directly — we don't need to do anything extra first.
VS Code's integrated Terminal: if a user types plain python/pip there, VS Code auto-activates the selected .venv for them silently when the terminal opens — but to keep things fully consistent, we can just always type uv add ... / uv run ... instead. It works the same whether or not the terminal happened to auto-activate anything.
Windows troubleshooting
Getting a “running scripts is disabled on this system” error? This happens on some Windows machines where PowerShell blocks scripts from running by default, which stops VS Code's terminal from activating our project's .venv:
.venv\Scripts\activate : File C:\Users\pongyuenlam\Documents\.venv\Scripts\Activate.ps1 cannot be loaded because running scripts is disabled on this system. For more information, see about_Execution_Policies at https:/go.microsoft.com/fwlink/?LinkID=135170.
At line:1 char:1
+ .venv\Scripts\activate
+ ~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : SecurityError: (:) [], PSSecurityException
+ FullyQualifiedErrorId : UnauthorizedAccess
Run the following once in PowerShell, then try again:
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
Getting an “is not recognized” error right after installing? (On a Chinese-language Windows PowerShell, this shows as “无法将‘uv’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”.) This means the terminal doesn't know about uv yet — almost always because it was already open before (or during) the install. The installer updates the system PATH, but a terminal that's already open won't notice until a new one starts:
uv : 无法将“uv”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写,如果包括路径,请确保路径正确,然后再试一次。
所在位置 行:1 字符: 1
+ uv --version
+ ~~
+ CategoryInfo : ObjectNotFound: (uv:String) [], CommandNotFoundException
+ FullyQualifiedErrorId : CommandNotFoundException
Fix: Fully close VS Code (not just the terminal tab), then reopen it and try uv --version again in a brand-new terminal.
If it still fails, the official installer may not have worked on that computer. This is common on school or company PCs, where some settings are locked. Install uv with one of these commands instead, in PowerShell opened from the Windows Start menu (search for “PowerShell”):
Option 1: Windows Package Manager (winget)
winget install --id=astral-sh.uv -e
Option 2: pip (only if Python is already installed on the computer)
pip install uv
Then fully quit and reopen VS Code once more, and check that it worked:
uv --version
If it shows a version number, such as uv 0.12.9, uv is ready. Continue with step 3 of Setup to install uv above.
Setup to run a Jupyter Notebook (.ipynb) program
A .ipynb file (short for “IPython Notebook”) is a Jupyter notebook — a document that mixes runnable code cells with text and their output, unlike a plain .py script which is just code. Learn more in the official Jupyter Notebook documentation.
A Jupyter notebook runs inside the same uv-managed project as a .py script, so steps 1 and 2 (uv init and uv add) from Setup to run a Python (.py) program above still apply first — a notebook needs an existing project (and its .venv) to attach to. Step 3 (uv run main.py) doesn't apply here, since we run notebook cells directly instead, as shown below.
Before opening a .ipynb file, make sure the Jupyter extension is installed in VS Code. Open the Extensions view (the square icon in the left sidebar), search for “Jupyter” (published by Microsoft), and click Install. This extension is what lets VS Code open and run notebook cells at all — without it, .ipynb files won't open as notebooks.
When we open a notebook cell for the first time, VS Code's Jupyter extension may show a prompt like:
Running cells with '... (3.12.10)' requires the ipykernel package.
Command: '.../.venv/bin/python -m pip install ipykernel -U --force-reinstall'
Don't run that command as shown — it will fail with No module named pip. uv-created virtual environments deliberately don't include pip; uv replaces it for installing packages. Instead, install ipykernel the same way as any other package:
uv add ipykernel
Then re-select the kernel in the notebook's top-right kernel picker (pick the project's interpreter again) and run the cell. A kernel is just the engine behind the scenes that actually runs our notebook's code — picking it here tells the notebook to use our project's .venv instead of some other Python installation.
General tips
- Always use VS Code's own built-in Terminal — no need to open a separate Terminal (Mac) or Command Prompt (Windows) app. We'll still need to type commands into VS Code's terminal and read what it shows us, such as the
uv --versioncheck or any error messages. (The one exception is the Windows “is not recognized” fix under Windows troubleshooting, which uses PowerShell opened from the Start menu instead.) - Restart VS Code once right after installing uv and Python. VS Code remembers the list of Python versions it found the last time it looked, so it won't notice the new one we have just installed until we restart VS Code. Afterwards, we can click the gear icon (⚙) at the bottom-left corner of VS Code, choose “Command Palette” from the menu that appears, and type “Python: Select Interpreter”.
Summary checklist for users
- Install uv (Mac:
curl -LsSf https://astral.sh/uv/install.sh | sh/ Windows:powershell -c "irm https://astral.sh/uv/install.ps1 | iex") - Close and reopen the terminal before running any
uvcommand -
uv --version(confirm it's found) -
uv python install 3.12.10 -
uv python pin 3.12.10(run this from our top-level projects folder) -
uv init(once per project, inside its own new folder — the folder name becomes the project name) -
uv add <package>to install packages -
uv run main.pyto run a.pyscript - Running a
.ipynbnotebook instead? Install the Jupyter extension in VS Code first - If VS Code prompts for
ipykernel, runuv add ipykernel(not the suggested pip command), then re-select the kernel - Fully quit and reopen VS Code after installing uv/Python, then use the gear icon (⚙) → Command Palette → “Python: Select Interpreter” to confirm the
.venvinterpreter is selected