How to correctly set PYTHONPATH for Visual Studio Code

Question

How do I correctly set up the $PYTHONPATH variable for my workspace in VisualStudio Code?

Background Information

I have installed two versions of GNURadio:

1. GNURadio version 3.7.11 installed by the Linux Mint package manager in /usr/lib/python2.7/dist-packages/gnuradio

2. GNURadio version 3.7.13.4 installed by PyBOMBS in /home/tejul/Documents/gr13/default/lib/python2.7/dist-packages/gnuradio (my prefix directory is ~/Documents/gr13/default)

I can use the newer version of GNURadio version only after I run the setup_env.sh script (which -- among other things -- adds /home/tejul/Documents/gr13/default/lib/python2.7/dist-packages to $PYTHONPATH) and then start python in the terminal

tejul@Wacom:~/Documents/gr13/default$ ls
bin  etc  include  lib  libexec  setup_env.sh  share  src
tejul@Wacom:~/Documents/gr13/default$ source ./setup_env.sh 
tejul@Wacom:~/Documents/gr13/default$ python
Python 2.7.15rc1 (default, Nov 12 2018, 14:31:15) 
[GCC 7.3.0] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> from gnuradio import gr
>>> gr.version()
'3.7.13.4'
>>> 

Without modifying the $PYTHONPATH python -- naturally -- imports the older version of GNURadio.

I want to write, run, and debug python scripts for the new version of GNURadio in the VisualStudio Code. I've been trying to understand the selection of python interpreters, workspaces, and environments for VSCode.

As far as I understand it, the VSCode workspace setting python.pythonPath is not to be confused with the environment variable $PYTHONPATH. python.pythonPath is the path to the python interpreter used for debugging or running the code, while $PYTHONPATH is the environment variable which python uses to search for modules.

It looks like PyBOMBS did not install its own python interpreter into my prefix directory. So I need to use VSCode with my normal python interpreter located in /usr/bin/python2.7. So redefining VSCode's python.pythonPath or selecting another python interpreter would not help me.

I need to let VSCode use my own version of the environment variable $PYTHONPATH which would tell my regular python interpreter to import modules preferably from /home/tejul/Documents/gr13/default/lib/python2.7/dist-packages.

Problem

Following the documentation, I have created my own .env file in the workspace directory which sets the order of preference for locations from which python should import the modules. Alas, it has no effect on the python interpreter.

Can you see anything that I am doing wrong here? I have also tried:

• Setting the PYTHONPATH to one folder level higher, i.e. /home/tejul/Documents/gr13/default/lib/python2.7, this did not help
• Calling the variable $PYTHONPATH instead of PYTHONPATH, this did not help
• Restarting VSCode after each change of the .env file, this did not help
• Using double quotes around the path string, e.g. PYTHONPATH="/home/tejul/Documents/gr13/default/lib/python2.7:/usr/lib/python2.7", this did not help

Sherbrooke

I did not manage to set the PYTHONPATH in Visual Studio Code, but I have found how to make VSCode inherit it from the systems environment variables. I have added these two lines to my .bashrc file: # setup python gnuradio environment source /home/tejul/Documents/gr13/default/setup_env.sh That automatically runs the setup_env.sh script for every terminal window. – Sherbrooke

see github.com/microsoft/vscode/issues/203607 – Yelenayelich

now at github.com/microsoft/vscode-python/issues/22824 – Yelenayelich

as of 2024-02 the ticket is closed - you might want to comment there to get it reopened or add another feature request ticket. – Yelenayelich

Answer 1

OP seemed to have asked about path syntax for the .env file and the vscode set up so that it finds and reads some custom module files. My problem was similar in that I wanted code to find my custom modules for import in a script. I did not want to put my custom modules in a folder inside my python environment. I also wanted to avoid setting one or more paths as PYTHONPATH for the User Variables in the Windows Environment Variables - but this will work if you want to do it. I am working in vscode in Windows 10.

1) SYNTAX:

a) I found that the following path syntax works in the env file:

PYTHONPATH = C:/0APPS/PYTHON/_MODULES

My .py module files are in this folder.

b) # works for comments in the .env file.

2) VSCODE SET-UP: I found that the following works:

a) Like sunew said at #2 My setup: Use the Explorer in vscode to open at your selected project workspace folder. For me that is Q:\420 PYTHON

b) Give the env file a name, like vscode.env file and place it in that folder at the top level of the workspace.

c) Open vscode settings and search .env where under the Extensions > Python you will find "Python: env file". Edit the box to add your env file name just before .env. e.g. ${workspaceFolder}/vscode.env

d) import custom_modulename now work for me - in the python interactive window and in a script.

Grandiloquent

Answer 2

I have a situation that I believe is relatively common. I want a script to import a module from another directory. My python project is laid out as follows:

~/project/
  |
  |---modules/
        |
        |---mod.py
  |---scripts/
        |---script.py

in script.py, I have from modules import mod. So my PYTHONPATH needs to be set to ~/project/ (something that PyCharm does automatically).

VSCode is a great editor, but everywhere else, it falls short, in my opinion. This is a perfect example of that.

I create a default launch.json file to "run the current file". A "cwd": "${fileDirname}" line has to be added to make things work like they do in PyCharm (FYI, a list of the built-in variables can be found here).

Debugging

For debugging (the "play" button on the sidebar, or the F5 key), the PYTHONPATH set in launch.json or your .env file takes effect. Note that in the .env file, you cannot use variables such as ${workspaceRoot}, but you can easily append or insert to the path by using the proper separator for your platform (; for Windows and : for everyone else).

Because I want to take advantage of that variable, I put this in my launch.json:

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

(Thanks to @someonr for the suggestion to use ${pathSeparator}.)

It appears that you can prepend/append to whatever is inherited from the environment (this is not true for settings.json; see below).

This will also work for the hotkey Ctrl+F5 (run without debugging).

For reference, here's the full file, which replicates what PyCharm does automatically:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Current File",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "cwd": "${fileDirname}",
            "env": {"PYTHONPATH": "${workspaceFolder}${pathSeparator}${env:PYTHONPATH}"}
        }
    ]
}

Run in terminal

If I hit the "play" button that appears on the top right of the editor window (when a python file is the active tab), it will not work. This runs the current file in a terminal, which doesn't pay attention to launch.json at all. To make that work, you have to define PYTHONPATH in a settings.json file, by adding this:

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

(Note there are different values for each platform.) If you've selected a python interpreter (e.g. from a virtual environment), you will already have a settings.json file in the .vscode directory. Mine looks like this:

{
    "python.pythonPath": "/Users/me/project/venv/bin/python3",
    "terminal.integrated.env.osx": {"PYTHONPATH": "${workspaceFolder}"}
}

You can't append or insert values into the inherited PYTHONPATH via the settings.json file. It will only take one string, and it will not parse separators. So even though you could get the value using ${env:PYTHONPATH}, you won't be able to do anything with it.

Moreover, you can't set the current working directory. Even though it would seem you could set it with "terminal.integrated.cwd": "${workspaceFolder}", it doesn't work. So if any of your scripts do anything with paths relative to their location in the tree, they won't work. The working directory will be your project root.

Note that any changes to the settings.json file will require that you exit the integrated terminal and restart it.

Linting

Nothing I do to launch.json regarding PYTHONPATH makes any difference to pylint, which will red-underline from modules import mod, despite the fact I can put the cursor on mod, hit F12, and the file opens. Snooping around linting settings, the defaults for mypy include --ignore-missing-imports. To replicate this behavior with pylint, add this to your settings.json:

    "python.linting.pylintArgs": [
        "--disable=F0401"
    ] 

Shame that we just have to work around this, but the autocomplete helps a lot when writing the import statements to begin with.

Conclusion

There are many layers to VSCode and it's hard to get things to work together. It seems multiple environments are floating around. In the end:

1. I cannot "run in terminal" because I can't set the current working directory to be the path containing the current file.
2. I cannot set PYTHONPATH for pylint as that runs in some environment different than the integrated terminal and whatever is controlled by launch.json, so I can only tell pylint to ignore import errors.
3. Running with F5 works if you set PYTHONPATH either via an .env file or in launch.json

Ehudd

after spending the better part of a day trying to get linting to work in a Multi-Root Workspace, I found that for the "python.envFile" setting, setting this in the Workspace config file (ie .code-workspace file) doesn't work but setting this (using your example) in scripts/.vscode/settings.json does the trick. You'll want to note that ${workspaceFolder} will be relative to the scripts folder. Anyway, I think that's what's going on... it's currently working for me. – Ahron

Also, I'm now noticing that the PYTHONPATH in the .env file must be absolute paths (or maybe relative to something but I'm not sure what). – Ahron

Thank you so much for this. I can debug but could NOT understand why running from the terminal was giving me ModuleNotFoundError. Do you have any leads on how/when VScode will be able to function normally across these settings? – Hypochondriasis

I've set up my PYTHONPATH to have multiple directories. And for this, I think I cannot put a cursor on my imports, nor can I follow their definitions. – Hypochondriasis

There is also running of notebooks (and iPython) which seems to be another config task. – Filamentous

pylint does not complain if i use the .env file, then restart vscode. it sucks that we have to restart..but it does work it seems. – Head

mypy ignores PYTHONPATH. You can use MYPYPATH instead. See github.com/python/mypy/issues/638 – Conservatoire

Now I'm working a lot with IPython (creating cells with the # %% comment) and the easiest solution I've come up with is to add import sys; sys.path.insert(0, sys.prefix + '/../') or similar at the top of the script. This adds one directory up from the Python interpreter's location to the Python path, so it works great if you have a virtual environment as a subdir of ~/project – Ehudd

in launch.json: add "env": {"PYTHONPATH": "${workspaceFolder}${pathSeparator}${env:PYTHONPATH}"} this one works for me on win11-vscode. – Hb

@someonr ${pathSeparator} is not : or ;. ${pathSeparator} is / for Linux/Mac or \ for Windows (source). Unfortunately, VS Code does not have a variable for : or ;, so .env PYTHONPATH= can't be cross platform if it has multiple entries. That's why I use pylint's --init-hook to prepend sys.path instead. – Crosspiece

@Ehudd You shouldn't disable pylint's missing import error. I know it's not easy, but it is fixable. You have to play around with adding __init__.py files, and setting sys.path properly. Either with PYTHONPATH or --init-hook "import sys, os; sys.path.insert(0, os.path.join('src', 'foo'))" – Crosspiece

@Crosspiece Thx! I deleted my misleading comment. Sorry for the confusion – Selfemployed

For linting you can edit "settings.json" and add ""python.autoComplete.extraPaths". Here you can mention the additional path to be scanned. – Terrilyn

when hitting the play button in upper right, is there a way to specify an environment file to load. in my case, i need to load different environments for windows vs linux. also, entries like '"terminal.integrated.env.osx" are not grayed out in settings.json – Head

I'm not sure why you say that the pythonpath and cwd don't work in the settings file. After restarting my terminal it worked perfectly for me. Separators and all! – Cleanser

Answer 3

The documentation is missing some important details.

Example

Suppose your project layout is like this

myproject/
    .vscode/
        settings.json
    .env
    src/
        a_module.py
    tests/
        test_a.py

Open the settings.json file and insert these lines

// On linux use "terminal.integrated.env.linux": {
"terminal.integrated.env.windows": {
    "PYTHONPATH": "${workspaceFolder}/src;${workspaceFolder}/tests"
},
// The next line can be omitted, unless you've modified the global default
"python.envFile": "${workspaceFolder}/.env",

Note that ${workspaceFolder} evaluates to myproject, it is not to the .vscode folder.

In the .env file enter this

PYTHONPATH=src;test
# Paths are relative to the workspace folder, so above is equivalent to
# WORKSPACE_FOLDER=C:/full/path/to/myproject
# PYTHONPATH=${WORKSPACE_FOLDER}/src;${WORKSPACE_FOLDER}/tests

Note that on Windows the slashes in the path lean forward, like so /. Different paths are separated with a ; on Windows (on other platforms with a :).

Final step, reboot VS Code.

This blog was helpful.

Vick

This worked for me to set PYTHONHASHSEED to a fixed value before opening VSCode. I put "python.envFile": "${workspaceFolder}/.env" in the settings.json file like you described and simply added PYTHONHASHSEED="0" to the .env file. Thank you! I have been trying to figure this out for a very long time. – Supercharger

I thought that vscode .env file doesn't do variable expansion like ${WORKSPACE_FOLDER}? "Variable substitution is only supported in VS Code settings files, it will not work in .env environment files." – Crosspiece

On that same page it says: "values can refer to any other environment variable that's already defined in the system or earlier in the file", which is what we're doing here. It seems the documentation is contradicting itself. – Vick

Still doesn't help, ModuleNotFoundError remains( – Selwin

I have two virtual environments, one for src and one for test, how to get that working? Also, I am confused about the workspace folder. In settings.json you are using workspaceFolder but in .env, you are using WORKSPACE_FOLDER. How will that work? – Neill

Modifying just .env works for me. What's the reason behind also modifying settings.json? – Redundant

Comment #1 The default location assumed for .env file is the root of your workspace, so you only need to use settings.json to specify a different location. – Moore

Comment #2 Environment variables defined in .env accept relative paths, so in the example above PYTHONPATH=src;tests is sufficient. Not only is there no need to define WORKSPACE_FOLDER, but doing so also makes the .env file non-transferrable (e.g. including it in git will likely cause issues across users). – Moore

Final step, reboot VS Code! – Formalin

Answer 4

Setting PYTHONPATH in .env works for me. Note that the effect just is for vscode and the tools it runs, such as pylint.

My situation: I have a project that is not a pip installable package, but simply a source folder. (For historical reasons...)

myproject/src

The project has dependencies defined in a pip requires file.

My setup:

1. I create a virtualenv, and install the packages from the requires file.
2. I open vscode in the folder myproject - so this becomes the root of the vscode "project".
3. I point vscode to use the virtualenv as the python interpreter. This will make imports of dependencies installed with pip work. (For linters, intellisense, etc)
4. To also make imports from my project source work for the linters (pylint especially) in vscode, I add a .env with this content, adding my project source folder to the PYTHONPATH:

PYTHONPATH=./src:${PYTHONPATH}

Alehouse

Please note: On Windows you MUST use semi-colons ';' as separator! PYTHONPATH definitions in env-files are not platform independent: code.visualstudio.com/docs/python/… It took me much too long to figure this out myself the hard way... – Hoyle

Answer 5

For tools like Pyright you can edit python.analysis.extraPaths in the workspace settings.json.

Example:

{
    ...
    "python.analysis.extraPaths": [
        "src/apps",
        "src/override_apps"
    ],
    ...
    // next lines can be different
    "python.linting.enabled": true, 
    "python.linting.pylintEnabled": true,
    "python.linting.mypyEnabled": false,
    "python.pythonPath": "environment/bin/python",
    ...
}

Fillister

Answer 6

Edit settings.json in your vs code workspace folder

{
"python.pythonPath": "*python package path*",
"terminal.integrated.env.windows": {
    "PYTHONPATH": "${workspaceFolder}/*sub folder*;*python package path*"
},
"python.defaultInterpreterPath": "*path to python exe*",
"python.analysis.extraPaths": [
    "*python package path*",
    "*python package path*"
],
"python.autoComplete.extraPaths": [
    "*python package path*",
    "*python package path*"
]}

Works good!

Grassland

Could you provide more information? What does that code do? – Grafting

so much redundancy here – Head

Answer 7

Linux user here. I had trouble getting it to work and there is a lot of interaction with other vscode Python extension settings, but the following worked for me:

• Close all workspaces.

• Add a single folder that you wish to be the root folder of your new workspace.

• Put your .env file there containing PYTHONPATH=/path/to/a:/path/to/b on a single line by itself. Do not use double quotes around the value.

• Restart vscode

• Create a test.py script that imports a package or module within your folder

• vscode should allow your import statement, and should autocomplete to code within your folder.

Refulgent

Answer 8

Two other issues that I spent a long time figuring out (despite the great answers above) which may help others:

1. Make sure that you have configured VS Code to allow terminal configurations to amend your shell settings (via Manage Workspace Shell Permissions (see https://code.visualstudio.com/docs/editor/integrated-terminal#_configuration). Otherwise VS Code silently ignores your terminal.integrated.env.{platform} settings.
2. Pylint will only search for other modules in the worspace directory if the module from which it is launched is in a folder which is a package (ie has _init_.py file) (See https://docs.pylint.org/en/1.6.0/run.html) meaning that pylint will continue to highlight import errors despite the code running properly due to the VS Code launch.json configured as above.

Perla

Answer 9

I also had a similar issue where I was using the vs-code on a remote server over ssh, the server had multiple user-accounts so the typical ubuntu python path did not work for me.

The easiest way, I have found for doing debugging was to first find out my own python install location using "which python". The output would be something like "/home/user_name/anaconda3/bin/python".

Then in vs-code, I manually set the python interpreter location to be the above location. I did this by clicking on the python tab on the bottom of vs code. like the Python 3.8.5 64-bit in this picture. This will open the command pallete asking for the location of python interpreter, as shown in this image. manually put the location of python install here. After doing all these steps, my python debugging is working smoothly.

Maun

I had a issue with "from pandas import Excelwriter". It thrown an error "ModuleNotFoundError: No model named 'pandas'. I follow exactly the same way. In the terminal run "which python". It returns the absolute path. Then add this path to the location of python interpreter. This solved my issue. Thanks a lot @SIDHARTH Kumar – Photography

Answer 10

Running VSCode 1.6.2, with Python extension v2021.10.1365161279 on Windows 10.

Debugging works based on the env file, I used the default file .env:
PYTHONPATH=<full_path_to_the_workspace_folder>

Running works based on the .vscode/settings.json file with such a setting
"terminal.integrated.env.windows": {"PYTHONPATH": "<full_path_to_the_workspace_folder>"}
just that I found I needed to disable+reload+enable the extension if I changed the path.

Sangraal

Answer 11

These are 3 different ways to solve the issue :

1/ Editing PYTHONPATH :

• export PYTHONPATH=/Users/.../Projects/MyNewProject/src
• python3 myfile.py to run the file

2/ Editing VSCode settings :

• add "terminal.integrated.env.osx": {"PYTHONPATH": "${workspaceFolder}/src"} to settings.json in VScode

3/ Adding a setup.py file to your src/ directory.

• create the file src/setup.py

from setuptools import find_packages, setup

setup(
    name="sample",
    description="Sample Python Project",
    packages=find_packages(),
)

• run python -m pip install -e ./src/ to install all modules in src/ as packages

Ephemera

Answer 12

After for reasons unknown my .venv/Lib/site-packages/.pth solution failed, as well as my subsequent .vscode\settings.json one, and an .env didn't work on my Windows 10*, I settled for the environment-independent way to import ./src/lib.py in ./test/test_lib.py:

import os, sys
sys.path.append(os.path.join(os.path.dirname(__file__), '../src'))
from lib import foo

That also works in non-IDE terminals, and VS Code's pycodestyle still complains when I forget an extra newline between functions.

*: VS Code 1.70.0 release note:

Loading environment variables from .env files

A number of fixes have been made to loading environment variables from .env files, including detecting changes to the .env files. Python kernels will now load environment variables from the file defined in the setting python.envFile.

Jeanicejeanie

Answer 13

Using VS Code, a pip virtual env, you can put at the end of the .venv/bin/activate file:

export PYTHONPATH="${PYTHONPATH}:/path/to/your/package"

package -> module1 -> abc.py and you can use: import module.abc etc.

Agan