How to debug Poetry application in Visual Studio Code

I have an application I have been given to take ownership of written using Poetry, I have some Python experience but have never used Poetry before. My editor of choice is Visual Studio Code (on Windows), however I can't figure out what to put in launch.json so I can debug the application.

If I am inside the application folder I can run it fine

app dostuff

poetry run app dostuff

However this does not seem possible outside the app, launch.json wants an absolute path and I cannot do

C:\users\me\app\app dostuff

I get an error saying the command is not found. If I don't provide an absolute path VS Code puts the current directory in front of if. I did try pointing at the generated file in the virtualenv

C:\Users\me\AppData\Local\pypoetry\Cache\virtualenvs\app-py3.9\Scripts\app dostuff

That just results in the program running in the terminal, no debugging.

Solution

I wrote this to be somewhat exhaustive for other readers, but the OP @Mant101 probably only needs to do sections (3.) and (4.) and read the last section "Some final (important) notes".

For other readers, you can just read the intro paragraphs for the numbered sections and "Some final (important) notes" and follow the numbered steps to (hopefully) arrive at a workable solution. The bullet points beneath the numbered steps either (a) explain what that step is doing, (b) explain some common issues for that step and how to troubleshoot them, or (c) give some additional context.

Assumptions

A.1. You're using Windows

A.2. VS Code is installed

A.3. VS Code's default terminal is PowerShell (I'll be using "terminal" and "PowerShell" interchangeably)

A.4. Poetry is installed

A.5. The Python extension by Microsoft from the VS Code extensions market place is installed

To check, use Ctrl + Shift + X in VS Code to open up the extensions market place and search "python". If it's installed, it won't have a button there to install it.

1. Setup Poetry project

This section will get Poetry to make some project folder/directory that already exists into an actual Poetry project. If you already have a pyproject.toml file & a poetry.lock file in the folder within which you want to debug files, then you can skip to the section "2. Using the Poetry virtual environment".

1.1. Open up VS Code

1.2. Open up the terminal within VS Code (keyboard shortcut: Ctrl + ` )

1.3. Change your directory to be the folder where your project exists with a PowerShell command like cd ~\path\to\my_project_folder

This is where the pyproject.toml & poetry.lock files will be created

1.4. Type poetry init into the terminal/PowerShell and press Enter.

Poetry will walk through the setup interactively and ask what packages you want for this project. After it's finished, it will create a pyproject.toml file. This file tells Poetry which versions of Python you're using, what packages, and any constraints. For example, it'll have the line python = ">=3.8,<3.11" if you tell it you only want Python 3.8 up to (but excluding) 3.11

1.5. Type poetry install into the terminal/PowerShell and press Enter.

This creates a poetry.lock file and a virutalenv for your Poetry project. It also installs all the packages specified in the pyproject.toml file within that virtualenv. Depending on how many packages you have, this could take a while

2. Using the Poetry virtual environment

This section creates a Poetry shell and activates the Poetry virtual environment that was created in step (1.5.). Strictly speaking, you don't need to do this to get the VS Code debugger working, but it might save you some keystrokes when you just want to run your Python file. Go to "Why you'd want to do (2.)" to see if this is worth bothering with. If you're in a hurry, just go with "Option 1" in the "Why you'd want to do (2.)" section to run Python files in Poetry.

2.1. Make sure you're in the project directory/folder with the pyproject.toml and type poetry shell into the terminal and press Enter

The exit terminal command will simultaneously deactivate the virtual environment and exit the Poetry shell
It's worth noting that the Poetry docs seem to recommend setting up a new shell instead of just activating the virtualenv

Why you'd want to do (2.): Saving keystrokes when running (not debugging) Python files

Say you don't want to use the debugger and just want to run your python file. You might be in the habit of going to the terminal and using python your_python_file.py (or python .\your_python_file.py when using PowerShell's Tab autocomplete).

So what's the issue? Well, say you have import pandas in your_python_file.py but pandas isn't installed globally (but you did use Poetry to install it, either during poetry init stage or with the terminal command poetry add pandas)... you'll probably get a ModuleNotFoundError: No module named 'pandas'.

You might be thinking, "Wait, didn't I install pandas with Poetry?" and the answer is yes, but only Poetry knows that. So you have a couple options:

Option 1: Run the Python file with Poetry (more keystrokes)

So instead of

python .\your_python_file.py

you can use

poetry run python .\your_python_file.py

This option probably isn't such a big hassle since you can use the up arrow key to get previously entered commands
This is probably a better option if you expect to be debugging a lot since the debugger doesn't work within the Poetry shell (read the section "Some final (important) notes" at the end)

Option 2: Create a Poetry shell and run the Python file

This involves doing (2.1.) first, and then you can use

python .\your_python_file.py

or, funny enough,

python your_python_file.py when using Tab autocomplete.

If you go with option 2, then you'll need to remember to use the terminal command exit when you want to run a Python file in a different Poetry project that has different packages and dependencies
You need to exit the shell if you want to use the VS Code debugger
It'll be pretty noticeable that you're in the Poetry shell since it's actually not a PowerShell (it's a Windows Command Prompt aka CMD), so commands like ls and cat your_python_file.py won't work

3. Change VS Code Python interpreter for Poetry

This section tells VS Code to use Python interpreter within the Poetry virtual environment.

3.1. Open the command pallet ( keyboard shortcut: Ctrl + Shift + P or F1 )

3.2. Search for "python: select interpreter" and select it with the mouse or navigate with the arrow keys and press Enter

3.3. Select "Enter interpreter path..."

3.4. Go back to the terminal/PowerShell ( keyboard shortcut: Ctrl + ` )

3.5. Type poetry env info --path and press Enter.

Note: If nothing shows up, then you probably don't have a virtualenv yet. You can check by using the poetry env info command and see if the "Path:" section has "NA". If this is the case, you can create a virtualenv by doing (1.5.). Then repeat step (3.5.)

3.6. Copy and paste the result of step (3.5.) into the prompt box at the top of VS Code that says "Enter path to a Python interpreter" and press Enter

4. Running & using the VS Code debugger

4.1. Open up the .py file you'd like to debug

4.2. Set any breakpoints you'd like the debugger to stop at

This can be done by clicking to the left of a line number. A red dot should appear

4.2. Press F5 to begin the debugger.

VS Code will probably pop up some options under "Select a debug configuration". If so, just select "Python file Debug the currently active Python file"

4.3. Press F11 to step through the program

Some final (important) notes

Any time you try to run the VS Code debugger, it'll use the Python interpreter you set up in section "3. Change VS Code Python interpreter for Poetry". Simply repeat those steps if you want to debug a different Poetry project
The VS Code debugger will only work when you're not in the Poetry shell. So if you went with option 2. in "Why you'd want to do (2.)", then you need to use the terminal command exit before running the debugger