PYTHONPATH in VSCode – everything you need to know

Python is a popular and easy to learn high-level programming language with an extensive ecosystem around it. It's no surprise that every major source code editor adds deep support for it, and VSCode is no exception. In this short article, you'll learn about PYTHONPATH and how to use it in conjunction with VSCode.

Python path : the environment variable vs VSCode settings

Python developers usually face a scenario where they want a script to import a module from another directory. The PYTHONPATH environment variable specifies the location where the Python intepreter should look for modules.

PYTHONPATH should be set before running the Python intepreter. One can specify the PYTHONPATH in an .env file or changing terminal.integrated.env.* key in VSCode settings.json. If needed, you can set PYTHONPATH using both methods.

When PYTHONPATH is set using an .env file, it will affect anything the extension does on your behalf and actions performed by the debugger, but it will not affect tools run in the terminal.

PYTHONPATH settings is particularly useful when you have a separate src folder for source code and run tests in tests folder. When running tests, however, those tests can't normally access modules in src unless you hard-code relative paths.

Please note that the value of PYTHONPATH can contain multiple locations separated by os.pathsep. It can be a semicolon (;) on Windows or a colon (:) on Linux/macOS. Invalid paths are ignored.

For more information on PYTHONPATH, read Python official documentation.

Set PYTHONPATH in VSCode

There are two ways to set PYTHONPATH in VSCode.

You can add the absolute path to src folder to PYTHONPATH by creating an .env file within your VS Code workspace with the following contents

PYTHONPATH=path_to_src

Then set python.envFile in your settings.json file to point to the .env file you just created. For example, if the .env file was in your workspace root, your settings.json would be set as shown:

// Specify .env file location in the root folder of your workspace
"python.envFile": "${workspaceFolder}/.env"

Alternatively, you can add the following lines of code in VSCode settings.json to achieve the same result.

// Modify PYTHONPATH to add current folder
"terminal.integrated.env.linux": {
    "PYTHONPATH": "${workspaceFolder}"
}

The settings above works for Linux-based system. If you're running VSCode on macOS, change terminal.integrated.env.linux to terminal.integrated.env.osx. Likewise, the key name for Windows is terminal.integrated.env.windows.

If you find that your value for PYTHONPATH isn't working as expected, make sure that you're using the correct separator between locations for the operating system. For example, using a colon to separate locations on Windows, or using a semicolon to separate locations on Linux/macOS results in an invalid value for PYTHONPATH, which will then be ignored.

We hope that the information above is useful to you. If you're interested in advanced editing features of VSCode, check out our post on how to enable/disable word wrap in VSCode, How to use LaTeX in VSCode or how to automatically indent your code in Visual Studio Code.