Running uv scripts in debug mode

[RubenVanEldik]

Hi all!

I am trying to see if we can start using uv to manage our codebases. Everything seems to work great, and managing dependencies is a lot easier this way! However, I can't figure out how to run a program through uv in debug mode in either VS Code or PyCharm. (e.g., uv run src/main.py) Does anyone have experience with running uv scripts in debug mode and can you point me in the right direction? :)

Thank you!

[zanieb]

Related to https://github.com/astral-sh/uv/issues/7803

We don't have a great recommendation here yet.

[emilyemorehouse]

I configured an alias (alias python="uv run python") and am able to debug apps/scripts without any modification to my VS Code config (and without forcing other devs to use uv if they aren't ready to migrate yet). I do feel like this is more of a workaround and has its pros/cons, but I'm happy with using this as a working solution to remove the barrier to utilizing uv.

[RubenVanEldik]

That's a great workaround @emilyemorehouse! I will definitely be using this myself as well. However, before I can convince the rest of my team that we should start using uv everywhere, it is important to have a less 'hacky' way to debug uv programs.

@zanieb, I fully understand this is not at the top of the priority list of uv right now, but I do think it is important to have some sort of solution for this when uv goes more mainstream :)

[franperezlopez]

I agree with @RubenVanEldik : if astral doesn't support common development scenarios (such as debug using vscode), all the other efforts will be meaningless. another way to see it: now vscode offers support for pip (pipx, ...) and conda (micromamba, ...) environments, so the day I see UV in that list, then I will talk about UV to other developers. I hope that day comes soon

[zanieb]

I understand the desire, but it seems like this is sort of something for the VSCode team to tackle. I don't understand the nuances of the debugger setup and if alias python="uv run python" works then it seems like there's not really a technical limitation just a weird constraint on how the Python interpreter is invoked?

[gresavage]

I understand the desire, but it seems like this is sort of something for the VSCode team to tackle. I don't understand the nuances of the debugger setup and if alias python="uv run python" works then it seems like there's not really a technical limitation just a weird constraint on how the Python interpreter is invoked?

I second this!

From what I can see, UV obeys the ancient PEP0405 so any issues with VSCode or PyCharm selecting the correct interpreter stem from the IDE, not UV.

FWIW I also had this issue initially and the alias python="uv run python" hack worked, but was actually no longer needed after restarting VSCode... Perhaps even just restarting the extension host would suffice.

[gresavage]

@franperezlopez UV abides by PEP0405. So the UV virtual environment is literally the same as choosing the Venv from the dropdown in the image you shared... it's nothing special and you should just be able to select the correct interpreter for the project as I have done (below).

UV will create a new virtual environment on uv sync or you can create one manually with uv venv. The resulting venv should appear as an option when selecting an interpreter for the project. I think you could even just choose the Venv option you showed, and UV will automatically sync packages to that venv.

I did have issues initially with VS Codes debugger using the right interpreter - but restarting VS Code fixed this... perhaps even just restarting the extension host would work. This strongly plus UVs PEP compliance indicates to me the issue lies with VS Code and not UV.

[AlexeyPetrochenko]

You can run your FastAPI application using the following configuration in launch.json:

{
    "name": "api",
    "type": "debugpy",
    "request": "launch",
    "module": "app",
    "console": "internalConsole",
    "justMyCode": true
}

In this configuration, "app" refers to the Python module that contains the file main.py. main.py Create a file named main.py with the following content:

import uvicorn

if __name__ == '__main__':
    uvicorn.run("app.server:create_app", host="127.0.0.1", port=8000, reload=True, factory=True)

Here, server.py is the entry point of the application, and create_app is the application factory function. Using a factory pattern is recommended for better flexibility. server.py In your server.py, define the application factory as follows:

from fastapi import FastAPI

def create_app() -> FastAPI:
    app = FastAPI()
    return app

Running the Application With this setup, you can run your FastAPI application in debug mode directly from Visual Studio Code. Simply select the configuration named "api" from the debug panel and start debugging. This configuration allows you to take advantage of debugging features such as breakpoints and variable inspection while developing your FastAPI application. Final Notes Ensure Dependencies: Make sure you have all necessary dependencies installed, including FastAPI and Uvicorn. Directory Structure: Ensure that your directory structure supports this setup, with main.py located in the correct module path.

├── app/                     
│   ├── __init__.py          
│   ├── __main__.py       
│   └── server.py 

[adithyakirank]

I think the more vs-code way of doing this until support for uv is added is:

1. Select the interpreter (uv run which python if you are not sure) with the command palette like here

2. Add the launch config for a script at ${workspaceFolder}/tests/test_script.py to launch.json

{
    "name": "my_test_script",
    "request": "launch",
    "cwd": "${workspaceFolder}/tests",
    "type":"debugpy",
    "program": "src/tests/test_script.py",
    "console": "integratedConsole",
    "args": [
        "arg1": "value1"
    ]
},

[emilyemorehouse]

FWIW I also had this issue initially and the alias python="uv run python" hack worked, but was actually no longer needed after restarting VSCode... Perhaps even just restarting the extension host would suffice.

This is exactly what happened to me. I've also ditched the alias and simply selecting the right interpreter in VS Code (from the venv that I create with uv and auto-activate with direnv) is working seamlessly.

I also agree that this isn't a uv issue – it's up to each debugger/editor to support uv-specific things that don't fit into this box.