Quickstart

A script is typically a lightweight program that solves a simple task and is portable.

When writing a Python script, you often need a place to include meta-information, such as package dependencies and the required Python version.

PEP 723 addresses this problem by introducing a way to write inline metadata directly into the script. Simply put, it’s just a comment with special syntax where you can define TOML-like configuration, similar to how you would in a pyproject.toml file.

A simple script that uses requests to send an HTTP request may look like this:

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "requests",
# ]
# ///

import requests

response = requests.get("https://github.com/karpetrosyan/uv-vscode")
print(response.status_code)

Okay, it looks like a script: it's lightweight, solves a simple task, and is portable.

And it's... it's so portable. You can just copy this code and send it to your friend using your favorite messenger (mine is Telegram), and that's it. Now your friend has everything needed to run this script without a missing dependency error or Python version incompatibility.

But it's just a PEP standard that defines how it should look. To actually run the script, there must be a tool that understands it, right? And that tool is our already lovely uv.

Assuming our script above is put in a file named script.py, we can now run it as follows:

>>> uv run script.py
200

Environment Auto-Switching

As VS Code states: an "environment" in Python is the context in which a Python program runs, consisting of an interpreter and any number of installed packages.

When working on a project in VS Code, you need to configure the virtual environment to point to the interpreter that has access to the dependencies your project needs, so the IDE can provide suggestions and autocompletion.

When using the extension, it will automatically switch the environment to a script's environment when you switch to, or save, a file that contains inline metadata. This ensures that you get autocompletion and all the necessary features when working with a Python script.

When you switch to a file that is not a script, the extension looks for the closest pyproject.toml, starting from the file's folder and going up to the folder opened in VS Code (never above it), and switches to the environment of that project.

This simplifies working with script files alongside your main project, and with several projects in one folder: every file uses the environment of the project it belongs to, and a script always uses its own.

If there is no pyproject.toml between the file and the opened folder, the environment is left as it is.

NOTE

The extension doesn't create the project's environment. If the project has no virtual environment yet, uv picks another Python interpreter that fits the project.

Untitled Files

A script doesn't have to be saved for any of this to work. Open a new untitled file, write or paste a script with inline metadata, and the extension will enter its environment shortly after you stop typing.

uv needs a real file to work with, so the extension keeps a copy of the untitled file in its own storage and runs uv against that copy. When a command changes the inline metadata, like add, remove or initScript, the change is applied back to the untitled file.

NOTE

For untitled scripts these commands are always executed directly, even when uv.sendUvCommandToTerminal is enabled, because the extension has to know when the command finishes to apply the changes back.

Run

If you’ve ever used VS Code to write Python code, you might have noticed that when using the Python extension, there’s a handy button you can press to run an individual Python file in a terminal.

Pressing that button simply makes the Python extension call the python command using the Python binary configured for your current active environment, passing the file as the first argument like so:

python /path/to/your/program/script.py

Here, python should be replaced with the path to the Python binary configured for your project in VS Code, which often looks like this:

/path/to/your/program/.venv/bin/python

But it just runs the file as a normal Python script, without respecting inline metadata like the script’s dependencies, etc. When uv-vscode is enabled, it recognizes that the current file is PEP 723-compatible and handles everything for you—just press the run button and wait for the magic!

The run button belongs to the Python extension, which can't run a file that was never saved. For untitled Python files the extension adds its own Run Script button next to it, which runs a copy of the file in a terminal. The same Run Script command is available in the Command Palette and works for saved scripts too.

Debug

There is also a debug option you can set by clicking the little dropdown menu next to the run button. It works similarly to regular debugging, but the extension ensures that the correct interpreter is used for debugging the script.