Blog

Setting Python source folders in Visual Studio Code

14 Jun, 2022
Xebia Background Header Wave

Visual Studio Code is my preferred editor. Unfortunately, it doesn’t work with additional Python source folders out of the box. This blog shows how to add a Python source folder and regain the developer experience you’ve come to love.

Although it’s common to use top-level modules, Python allows you to organize your project any way you want. The src-based module layout uses a src-folder to store the top-level modules.

Basic module layoutSrc-based module layout
/project/module.py/project/src/module.py
/project/tests/test_module.py/project/tests/test_module.py
/project/requirements.txt/project/requirements.txt

To configure Python to search for modules in the src-folder we alter the default search path. In PyCharm this is done by selecting a source folder. In Visual Studio Code, this is done by setting the PYTHONPATH variable.

Add source folder to PYTHONPATH

Modify settings.json to include the source folder “src” in the integrated terminal:

<span class="token punctuation">{</span>
  <span class="token property">"terminal.integrated.env.osx"</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token property">"PYTHONPATH"</span><span class="token operator">:</span> <span class="token string">"${workspaceFolder}/src"</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
  <span class="token property">"terminal.integrated.env.linux"</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token property">"PYTHONPATH"</span><span class="token operator">:</span> <span class="token string">"${workspaceFolder}/src"</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
  <span class="token property">"terminal.integrated.env.windows"</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token property">"PYTHONPATH"</span><span class="token operator">:</span> <span class="token string">"${workspaceFolder}/src"</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
  <span class="token property">"python.envFile"</span><span class="token operator">:</span> <span class="token string">"${workspaceFolder}/.env"</span>
<span class="token punctuation">}</span>
JSON

And add or modify .env to include the source folder “src” in the editors’ Python environment:

<span class="token constant">PYTHONPATH</span><span class="token attr-value"><span class="token punctuation">=</span>./src</span>
Ini

Note that the PYTHONPATH must be set for both the editors’ Python environment and the integrated terminal. The editors’ Python environment is used by extensions and provides linting and testing functionality. The integrated terminal is used when debugging to activate a new python environment.

Remark This configuration overwrites the existing PYTHONPATH. To extend, use the following settings:

<span class="token punctuation">{</span>
  <span class="token property">"terminal.integrated.env.osx"</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token property">"PYTHONPATH"</span><span class="token operator">:</span> <span class="token string">"${env:PYTHONPATH}:${workspaceFolder}/src"</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
  <span class="token property">"terminal.integrated.env.linux"</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token property">"PYTHONPATH"</span><span class="token operator">:</span> <span class="token string">"${env:PYTHONPATH}:${workspaceFolder}/src"</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
  <span class="token property">"terminal.integrated.env.windows"</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token property">"PYTHONPATH"</span><span class="token operator">:</span> <span class="token string">"${env:PYTHONPATH};${workspaceFolder}/src"</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span>
<span class="token punctuation">}</span>
JSON
<span class="token constant">PYTHONPATH</span><span class="token attr-value"><span class="token punctuation">=</span>${PYTHONPATH}:./src # Use path separator ';' on Windows.</span>
Ini

Resume development

There is no need to reload the workspace. Just open any Python file and enjoy the editors’ capabilities. Please note that it’s safe to include the settings.json file in source control.

If you dislike this additional configuration, feel free to restructure your project. Using the top-level module structure or by creating packages.

Laurens Knoll
As a cloud consultant I enjoy taking software engineering practices to the cloud. Continuously improving the customers systems, tools and processes by focusing on integration and quality.
Questions?

Get in touch with us to learn more about the subject and related solutions

Explore related posts