Introduction

When VS Code says an import cannot be resolved but the code runs in a terminal, the problem is usually editor configuration rather than Python itself. Pylance, Pylint, and the runtime all need the same interpreter and import paths, and they often drift apart in projects that use virtual environments or a src layout.

Start with the Selected Interpreter

Pylance and Pylint inspect code using the interpreter selected for the workspace. If VS Code points at the wrong Python binary, installed packages and local project paths will look missing.

Check the interpreter in the command palette or the status bar, then verify it matches the terminal you actually use.

python --version
which python
python -m pip show your-package

If the terminal and VS Code disagree, fix that first before changing any lint settings.

Understand the Difference Between Runtime and Editor Resolution

Python resolves imports from sys.path at runtime. Pylance performs static analysis and needs to know the same search roots ahead of time. Pylint also needs those paths when it analyzes modules.

A project with this structure is common:

1project/
2    src/
3        app/
4            __init__.py
5            main.py
6            utils.py

If VS Code opens the repository root but does not treat src as an import root, from app.utils import helper may work in some terminals yet still show warnings in the editor.

Configure extraPaths for a src Layout

Pylance can be told about additional import roots in workspace settings.

1{
2  "python.analysis.extraPaths": [
3    "./src"
4  ]
5}

Place that in .vscode/settings.json for the workspace. This helps Pylance resolve packages that live under src instead of directly under the repository root.

Keep Pylint in Sync

Pylint may still complain even after Pylance is satisfied if its import path differs. One simple fix is to run Pylint from the same environment and working directory your project expects. In some teams, adding a project-level launch or task configuration is enough. Another option is to expose the same search path through an environment variable.

export PYTHONPATH=./src
pylint src/app/main.py

If you want VS Code to pass that environment to tools, a workspace .env file can help.

PYTHONPATH=./src

Then point VS Code at it if needed.

Package Layout Still Matters

Sometimes the warning is correct. If your directories are meant to be packages, make sure the package structure is clear and the imports are consistent.

from app.utils import helper

versus

from .utils import helper

If a file is meant to run as part of a package, prefer launching it as a module:

python -m app.main

That aligns the runtime with the package layout and often removes both editor and terminal confusion.

Multi-Root Workspaces and Monorepos

In monorepos, VS Code may open one folder while the Python package actually lives in another. In that case, interpreter selection alone is not enough. You may need workspace-specific extraPaths, one virtual environment per service, or separate VS Code workspaces so each Python tool sees the right root.

A Practical Minimal Setup

For many src-layout projects, the following is enough:

1{
2  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
3  "python.analysis.extraPaths": [
4    "./src"
5  ]
6}

Then create the environment and install dependencies there.

python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

The exact path format differs on Windows, but the principle is the same.

Common Pitfalls

The most common mistake is selecting the wrong interpreter in VS Code and then trying to fix the symptom with extra path settings. Another is assuming Pylance and Pylint share identical resolution rules without configuration. Developers also often open the wrong folder in a monorepo, so the editor root does not match the Python package root. Finally, adding arbitrary paths until the warnings disappear can mask a packaging problem that should really be fixed with a clearer project layout.

Summary

• Make sure VS Code uses the same interpreter as your working terminal.
• Use python.analysis.extraPaths when your code lives under src or another non-root directory.
• Keep Pylint and runtime import paths aligned, often with the same environment or PYTHONPATH.
• Prefer python -m package.module for package-based entry points.
• Fix project layout issues directly instead of piling on editor-specific workarounds.