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 install

Answer 1

This question deserves an upvote because 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 fie and insert these lines

"terminal.integrated.env.windows": {
    "PYTHONPATH": "${workspaceFolder}/src;${workspaceFolder}/tests"
},
"python.envFile": "${workspaceFolder}/.env",

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

In the .env file enter this

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 other platforms with a :).

This blog was helpful.

Answer 2

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.

Answer 3

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}

Answer 4

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.

Answer 5

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}:${env:PYTHONPATH}"}

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}:${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