Lepidopterist's comment proved to be the game changer of hours of struggling...

Solution

1. Press Ctrl + Shift + P to open the Command Palette

2. Go to Users.setting.json

3. Add the following line:

   "terminal.integrated.env.windows": { "PYTHONPATH": "${workspaceFolder}" }

For reference: Settings.json

Explanation

This was my project structure...

Project

I had three modules/packages inside my project!

• module_a + module_b: performing standalone tasks
• convenience: provides utility functions to all other modules

What I wanted to do!

• keep all utility functions inside the convenience module and import them to whichever module that requires them

What did not work!

• Relative imports failed

  from ..convenience.utilities import add

  gave...

   beyond top level package error
  

• Absolute imports also failed

  from convenience.utilities import add

  gave...

   ModuleNotFoundError: No module named 'convenience'
  

• Adding Workspace directory to PYTHONPATH also failed

  "env": {"PYTHONPATH": "${workspaceFolder}"}

  gave...

   ModuleNotFoundError: No module named 'convenience'
  

Why did the solution (I mentioned at the start) work?

• Because I was running the module_a/task.py, using the integrated terminal. It makes sense that, Pythonpath needs to be appended for the terminal where we add the path of our workspace directory.

(One thing to note): My operating system was Windows, so it was...

"terminal.integrated.env.windows"

For Linux, it would be...

"terminal.integrated.env.linux"

Result after modifying Users.Setting.json:

Output

I tried to add this in my launch.json, then it works!

"env": {"PYTHONPATH": "${workspaceRoot}"}

below is my launch.json

        "name": "Python: Current File (Integrated Terminal)",
        "type": "python",
        "request": "launch",
        "program": "${file}",
        "cwd": "${workspaceRoot}",
        "env": {"PYTHONPATH": "${workspaceRoot}"},
        "console": "integratedTerminal"

wish it can help u! :)

After installing a new module via pip, if VS Code doesn't recognize it, then reloading VS Code may work.

Make sure the module is installed inside the virtual environment by creating and activating a virtualenv:

python3 -m venv env
source env/bin/activate

Use the correct way of installing a module with pip (Brett Cannon's article):

python3 -m pip install module_name

Replace the string "module_name" with your desired module name.

Reload VS Code by pressing Ctrl+Shift+P, and selecting Reload window.

Now it will know the new module and auto completion works.

Consider especially in new distribution like Debian 12 (Bookworm) with newer Python 3, always use a virtual environment to manage Python packages.

This is based on PEP 668, Marking Python base environments as “externally managed”.

For any new project, always create a new environment with:

python3 -m venv env

And activate it by running source env/bin/activate, and then install packages on it by pip.

Check if module_name is installed in current active virtualenv:

pip freeze

To deactivate the current active virtual environment, i.e., env run,

deactivate

Also it is worth mentioning to use the Python venv module, we must install it before.

For a Debian-based machine, here is the install command:

sudo apt install python3-venv

And same things for pip module for install a new python package.

For a Debian-based machine, here is the install command:

sudo apt install python3-pip

You can try the following:

{
    "name": "Python: A name example",
    "type": "python",
    "request": "launch",
    "program": "practice1/my_module.py",
    "env": {
        "PYTHONPATH": "${workspaceFolder}"
    },
}

• Using program instead of module is almost the same.
• You need to solve the imports as if you had the package installed. Therfore you need to add a PYTHONPATH.

It's easier than we imagine:

This image explains how to solve this problem.