English | 简体中文 | 日本語

Quickstart: Setting Up a Python Environment on Windows with uv

This guide will walk you through setting up a Python development environment on Windows using uv, an extremely fast Python packager and project manager from the creator of Ruff. Think of uv as a much faster, all-in-one replacement for venv and pip.

Prerequisites

• Windows OS
• Python installed (this guide uses Python 3.12 as an example)
• Windows PowerShell

---

Step 1: Install uv

First, we need to install uv. You have two options.

Method 1: Official Script (Recommended)

1. Search for PowerShell in the Start Menu, then select "Run as Administrator".

   

2. In the administrator PowerShell window, execute the following command to automatically download and install uv:

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

Method 2: Using pip

If you already have a working Python environment, you can also install uv via pip:

pip install uv

Verify the Installation

Once installed, run the following command to check the uv version and confirm it was installed correctly.

uv --version

You should see version output similar to the image below:

Step 2: Create and Activate a Virtual Environment

A best practice is to create an isolated virtual environment for each project.

1. In your project folder (e.g., D:\uv-test), open a PowerShell terminal.

2. Use the following command to create a virtual environment named .venv using Python 3.12:

   uv venv --python 3.12

3. Activate the Virtual Environment

   To use the new environment, you must activate it.

   Note: PowerShell's default security policy may prevent you from running scripts. Run the command below to allow script execution for the current session.

   Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

   When prompted, type Y and press Enter.

   Now, run the activation command:

   .venv\Scripts\activate

   Once activated, your command prompt will be prefixed with (.venv), as shown below.

   

Step 3: Initialize the Project and Install Dependencies

With the environment active, you can manage your project's dependencies.

1. Initialize the Project

   Running uv init creates a pyproject.toml file in your directory. This file tracks your project's metadata and dependencies, acting as a modern alternative to requirements.txt.

   uv init

2. Add Dependencies

   Let's install some common data science libraries. The uv add command installs packages and automatically adds them to your pyproject.toml. We'll use the -i flag to specify a faster mirror for quicker downloads.

   uv add numpy pandas matplotlib scikit-learn seaborn -i https://pypi.tuna.tsinghua.edu.cn/simple

   uv will resolve and install these packages at incredible speed.

---

Congratulations!

You have successfully created a clean, isolated Python development environment with uv.

Next Steps & Common Commands:

• List installed packages: uv pip list
• Deactivate the environment: deactivate

---

If you found this guide helpful, feel free to check out my blog at blog.mashijian.com for more hands-on tutorials and tech insights on AI, LLMs and Deep Learning!