Fix: Pylance Error "Import could not be resolved from source file" in VS Code

Understanding the Pylance Import Error

The error Import "module_name" could not be resolved from source file is a frequent issue encountered by Python developers using VS Code with the Pylance language server. It indicates that while your code might actually run correctly in the terminal, Pylance (the static type checker) cannot locate the source code for the imported module to provide IntelliSense, type checking, and navigation features.

# Example of the error appearing in the editor
import requests  # Error: Import "requests" could not be resolved from source file
from my_local_module import helper # Error: Import "my_local_module" could not be resolved from source file

This happens because Pylance looks for modules in a specific set of paths, and if your environment is not configured correctly within VS Code, it fails to map the import to a physical file on your disk.

Step 1: Verify the Python Interpreter

The most common cause is that VS Code is using a different Python interpreter than the one where your packages are installed. For instance, you might have installed pandas in a virtual environment (venv), but VS Code is using the global system Python.

• Press Ctrl + Shift + P (Windows/Linux) or Cmd + Shift + P (macOS) to open the Command Palette.
• Type Python: Select Interpreter and select it.
• Choose the interpreter that corresponds to your virtual environment. It usually looks like ./venv/bin/python or ('venv': venv).

Wait a few seconds for Pylance to re-index. If the red squiggly line disappears, the interpreter mismatch was the culprit.

Step 2: Configure Extra Paths for Local Modules

If you are working with a non-standard project structure, such as putting all source code in a src/ directory, Pylance might not know to look inside that folder for imports.

To fix this, you need to tell Pylance about these extra directories via the settings.json file.

• Create or open the .vscode/settings.json file in your project root.
• Add the python.analysis.extraPaths setting:

{
    "python.analysis.extraPaths": [
        "./src",
        "./path/to/your/custom/modules"
    ]
}

This tells the Language Server Protocol (LSP) to include these directories when searching for module definitions.

Step 3: Check the Workspace Root

Pylance resolves paths relative to the folder currently open in VS Code. If you open a "parent" folder that contains multiple sub-projects, Pylance may get confused about the import roots.

The Fix: Always open the specific project root folder as the workspace in VS Code. If you have a structure like /projects/my_python_app/, open my_python_app directly rather than the projects folder.

Step 4: Use a .env File for PYTHONPATH

Sometimes, your code relies on the PYTHONPATH environment variable to find modules at runtime. Pylance can also respect these settings if you use a .env file.

• Create a file named .env in your project root.
• Add your source directory to the path:

PYTHONPATH=src

• In your .vscode/settings.json, ensure the env file is loaded:

{
    "python.envFile": "${workspaceFolder}/.env"
}

Step 5: Refresh the Pylance Language Server

Occasionally, Pylance's internal index becomes stale or corrupted, especially after a large pip install session. Restarting the server can force a re-scan of your site-packages.

• Open the Command Palette (Ctrl + Shift + P).
• Type Python: Restart Language Server.

Verification: How to Confirm the Fix Worked

To ensure the issue is resolved properly, perform these checks:

• Visual Check: The red squiggly line under the import statement should disappear.
• Go to Definition: Hover over the imported module name, hold Ctrl (or Cmd), and click it. If VS Code opens the source file of that module, the path resolution is working.
• IntelliSense: Type the module name followed by a dot (e.g., module_name.). If a list of functions and classes appears, Pylance has successfully indexed the module.

Summary Tips

• Always use a virtual environment (python -m venv venv) to keep dependencies isolated.
• If you just installed a package, give Pylance a moment to index it before assuming there is an error.
• Check your pyrightconfig.json or pyproject.toml if you are using those for type checking configuration, as they can override VS Code settings.