Sign in Subscribe

Pylance Missing Imports Poetry Hot ((better))

Pylance “Missing imports” with Poetry — quick write-up

Problem summary

  • When using VS Code with the Pylance language server, you may see “Missing import” or “Import could not be resolved” for packages that are installed and work at runtime. This commonly happens when the editor’s Python environment and Poetry’s virtual environment don’t match, or when Pylance can’t find the virtualenv paths Poetry uses.

Why it happens (concise)

  • Poetry creates isolated virtual environments outside the project by default.
  • VS Code / Pylance must be configured to use that same interpreter and its site-packages.
  • Pylance sometimes uses a different interpreter, or the workspace settings don’t expose Poetry’s paths, causing stale import resolution.

How to fix (step-by-step)

  1. Select the correct Python interpreter in VS Code
    • Command Palette → Python: Select Interpreter → choose the interpreter that points to Poetry’s virtualenv (path typically includes .cache/pypoetry/virtualenvs or .venv if you created one inside the project).
  2. If Poetry uses a project-local .venv, enable it
    • Create the venv inside the project: poetry config virtualenvs.in-project true then poetry install. VS Code auto-detects .venv better.
  3. Point Pylance to the right extra paths (if needed)
    • In workspace settings (settings.json) add: "python.analysis.extraPaths": ["./.venv/lib/pythonX.Y/site-packages"]
    • Replace X.Y with your Python minor version and use the full path relative to workspace if not in-project.
  4. Use Poetry to show the interpreter path
    • poetry env info -p — copy the path and in VS Code pick that Python binary (.../bin/python).
  5. Restart VS Code/Pylance
    • After switching interpreters or changing settings, reload the window (Developer: Reload Window) so Pylance reindexes.
  6. Ensure dependencies are installed in the venv
    • poetry install or poetry add <pkg> so site-packages actually contain libraries Pylance should see.
  7. For editable or local packages
    • If you’re developing a local package, use poetry add -D -E . or poetry install with proper pyproject config so imports resolve.
  8. Configure Pylance type checking (optional)
    • If Pylance still flags unresolved imports but runtime is fine, you can relax checks: "python.analysis.diagnosticMode": "openFilesOnly"
    • Or set "python.analysis.packageIndexDepth": 3 for deeper package scanning.

Common pitfalls

  • Using a global interpreter in VS Code while Poetry’s venv contains the packages.
  • Hidden mismatch when Poetry creates venvs in a different Python version than VS Code selected.
  • Wrong extraPaths (pointing to incorrect Python version/site-packages).
  • Relying on system PATH rather than selecting the explicit interpreter binary.

Troubleshooting checklist

  • Run poetry env info -p and verify VS Code uses that Python.
  • Open a VS Code terminal and run python -c "import pkg; print(pkg.__file__)" to confirm the same interpreter is used.
  • Check which python/python -V in both VS Code integrated terminal and your shell where Poetry runs.
  • Clear Pylance cache by reloading window or reinstalling the extension if behavior persists.

Short recommended workflow

  • Enable in-project venv: poetry config virtualenvs.in-project true
  • poetry install
  • In VS Code select the .venv interpreter
  • Reload window

Result

  • Pylance will index the correct site-packages, removing “Missing import” warnings while preserving Poetry’s dependency isolation.

Resolving Missing Imports with Pylance and Poetry

When working with Python projects, managing dependencies and imports can become a challenge. This is especially true when using tools like Pylance for language server functionality and Poetry for dependency management. If you're encountering issues with Pylance not recognizing imports managed by Poetry, you're not alone. This guide will walk you through understanding the issue and implementing a solution.

🚫 When These Fail

  • Poetry not installed in the VS Code terminal’s PATH – restart VS Code from terminal or set poetry path in settings.
  • Pylance cache corruption – Ctrl+Shift+P → Python: Clear Cache and Reload Window.
  • Windows + WSL – ensure VS Code server is installed in WSL and interpreter points to WSL’s Poetry env.

Case 4: Using Conda + Poetry (Over-engineering)

Some developers use Conda for Python versions and Poetry for packages. This creates a nested environment confusion. pylance missing imports poetry hot

Fix: Don't. But if you must: Install Poetry in your Conda base, then use poetry config virtualenvs.create false to force Poetry to use the current Conda environment. Then point Pylance to the Conda environment's Python binary.

Case 2: The "Editable Install" Trap (Dev Dependencies)

Poetry installs your own project in editable mode (pip install -e .). Pylance can sometimes fail to resolve local modules.

Fix: Ensure your pyproject.toml includes your project package correctly: Pylance “Missing imports” with Poetry — quick write-up

[tool.poetry]
name = "myproject"
packages = [include = "myproject", from = "src"]

Then, update your settings.json as shown above with python.analysis.extraPaths.