DEV Community

ライフポータル
ライフポータル

Posted on • Originally published at code-izumi.com

Mastering "uv" in VS Code: The Ultra-Fast Python Setup Guide

#python #programming

In the Python ecosystem, managing packages and virtual environments has always been a point of friction. While tools like pip, poetry, and pipenv have served us well, a new Rust-based contender called "uv" has taken the community by storm with its incredible speed and simplicity.

Are you facing these challenges?

  • "I want to try uv but don't know how to set it up in VS Code."
  • "The VS Code interpreter won't recognize my uv environment."
  • "I'm struggling to get the debugger working with uv."

In this guide, we’ll walk through the best practices for using uv with Visual Studio Code. We’ll cover everything from installation to virtual environment recognition, debugging, and integrating with Ruff for the ultimate Python development experience.

What is "uv"?

Developed by Astral (the team behind Ruff) and written in Rust, uv is an extremely fast Python package installer and resolver.

It is designed to be a "one-stop-shop" replacement for pip, pip-tools, and virtualenv. Benchmarks show it to be 10x to 100x faster than traditional tools. For VS Code users, this means:

  • Instant Environment Setup: No more waiting for dependency resolution.
  • Disk Space Efficiency: Optimized global caching.
  • Consistency: The uv.lock file ensures your team is always on the exact same environment.

Step 1: Installing uv

First, install uv using the official recommended installer.

Mac / Linux 

curl -LsSf [https://astral.sh/uv/install.sh](https://astral.sh/uv/install.sh) | sh
Enter fullscreen mode Exit fullscreen mode

Windows (PowerShell) 

powershell -c "irm [https://astral.sh/uv/install.ps1](https://astral.sh/uv/install.ps1) | iex"
Enter fullscreen mode Exit fullscreen mode

After installation, verify it by running uv --version in your terminal.

Step 2: Getting VS Code to Recognize uv

To make VS Code's Python extension work seamlessly with uv, follow these steps to manage your virtual environment (.venv).

1. Initialize and Create venv

In your project directory, run:

# Initialize the project (creates pyproject.toml)
uv init

# Create the virtual environment (creates .venv folder)
uv venv
Enter fullscreen mode Exit fullscreen mode

2. Select the Interpreter

  1. Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P).
  2. Type and select "Python: Select Interpreter".
  3. You should see the Python version located inside .venv. Select it.

Tip: If the environment doesn't appear, add the following to your VS Code settings.json to ensure the .venv folder is indexed:

{
  "python.venvPath": ".",
  "python.venvFolders": [".venv"]
}
Enter fullscreen mode Exit fullscreen mode

Step 3: Package Management (uv add / sync)

Adding libraries is straightforward. uv automatically updates your pyproject.toml and uv.lock files.

# Add a production package
uv add fastapi

# Add a development package
uv add --dev pytest
Enter fullscreen mode Exit fullscreen mode

When team members join the project, they can sync their entire environment in a split second using:

uv sync
Enter fullscreen mode Exit fullscreen mode

Step 4: Debugging Configuration (launch.json)

To enable debugging (F5), create a .vscode/launch.json file. While the standard Python debugger works, it’s best to be explicit.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Current File (uv)",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "justMyCode": true
        }
    ]
}
Enter fullscreen mode Exit fullscreen mode

Now you can set breakpoints and debug your code directly within the uv-managed environment.

Pro Tip: Integration with Ruff

Since Ruff (the linter/formatter) is made by the same developers, it pairs perfectly with uv.

  1. Install the Ruff extension for VS Code.
  2. Add Ruff to your project: uv add --dev ruff.
  3. Set Ruff as your default formatter in settings.json: 
{
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.fixAll": "explicit",
      "source.organizeImports": "explicit"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Now, your code will be linted and formatted at lightning speed every time you save.

Conclusion

Switching to uv is perhaps the single most impactful change you can make to improve your Python developer experience in 2026. Combined with the power of VS Code and Ruff, you get a development environment that is not only fast but also robust and modern.

Originally published at: [https://code-izumi.com/python/uv-vscode/]

Top comments (0)