fix/duckdb/import-could-not-be-resolved
DuckDB error

Import "duckdb" could not be resolved

Updated Aug 27, 20265-min read
TL;DR

This is a Pylance warning inside VSCode, not a DuckDB runtime error. Pylance cannot find a duckdb package in the Python interpreter it is analyzing your file against, which is almost always because the interpreter VSCode picked is different from the one where you ran pip install duckdb.

  • ·VSCode is using a different Python interpreter than the one where duckdb was installed
  • ·You installed duckdb into a virtualenv, conda env, or Poetry env that VSCode has not been pointed at
  • ·duckdb was installed globally but the workspace has a .venv that VSCode auto-selected
  • ·The interpreter is correct but the environment was created before duckdb was installed and Pylance has stale state
  • ·You are on Python 3.13+ and installed a duckdb version that has no wheel yet for that interpreter
CHECK FIRSTOpen the Command Palette, run Python: Select Interpreter, and confirm the selected interpreter matches the one where python -m pip show duckdb succeeds in a terminal.

What you're seeing

The squiggle appears under the import statement in your editor. The script itself may still run fine from the terminal; the warning is Pylance's static analysis reporting that it cannot find the module for type-checking and autocomplete.

text
Import "duckdb" could not be resolvedPylance(reportMissingImports)

# Or, when the package is found but stubs are missing:
Import "duckdb" could not be resolved from sourcePylance(reportMissingModuleSource)

# In the Problems panel:
Import "duckdb" could not be resolved
Pylance  reportMissingImports  Line 1, Column 8
Also seen as: import "duckdb" could not be resolved pylance, import duckdb could not be resolved from source, reportMissingImports duckdb, vscode import duckdb could not be resolved, pylance cannot find duckdb

What's causing this

Ranked most-likely first.

  1. 1

    VSCode is pointed at the wrong Python interpreter

    This is the cause in the large majority of cases. You ran pip install duckdb in one Python (often the system Python or an activated venv in a terminal) but VSCode's Python extension picked a different interpreter for the workspace. Pylance then analyzes against that other interpreter, where duckdb is not installed.

  2. 2

    You installed duckdb outside the workspace virtualenv

    If the workspace contains a .venv or venv directory, VSCode auto-selects it. Running plain pip install duckdb in a terminal without activating that venv installs duckdb into a completely different Python. The import resolves at runtime only if you also run the script with the same non-venv Python.

  3. 3

    reportMissingModuleSource: duckdb is installed as a stub-only or binary-only wheel

    The variant "could not be resolved from source" is a different Pylance diagnostic. It means Pylance found the package's metadata but not a Python source or py.typed marker it can index. For duckdb this can happen with older versions or unusual install paths. The import will run fine, but autocomplete is degraded.

  4. 4

    No duckdb wheel exists for your Python version

    When a new Python (e.g. 3.13, 3.14) ships, duckdb wheels lag behind by a few weeks. pip install duckdb may print a message about no matching distribution, fall back to a broken build, or silently install nothing. Pylance then reports the module as unresolved because it truly is not there.

  5. 5

    Pylance's language server has stale state

    If you installed duckdb into the currently selected interpreter but the squiggle persists, Pylance may not have re-indexed. This is uncommon but real, and a Python: Restart Language Server usually clears it.

How to fix it

Step 1: confirm which interpreter VSCode is using

The status bar at the bottom of VSCode shows the current interpreter, or open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P) and run Python: Select Interpreter. Note the full path shown for the current selection.

text
Command Palette -> Python: Select Interpreter

Look for a path like:
  /Users/you/.venv/bin/python
  C:\Users\you\project\.venv\Scripts\python.exe
  /opt/homebrew/bin/python3.12
  /usr/local/anaconda3/envs/analysis/bin/python

Step 2: confirm duckdb is installed in THAT specific interpreter

Do not check with a generic pip. Call the exact interpreter path from Step 1 and ask it directly. If this prints an error, that interpreter does not have duckdb.

bash
# macOS / Linux. Use the path VSCode showed:
/Users/you/.venv/bin/python -m pip show duckdb

# Windows PowerShell:
& "C:\Users\you\project\.venv\Scripts\python.exe" -m pip show duckdb

# Should print: Name: duckdb, Version: ...
# If it prints "Package(s) not found", install into THIS interpreter:
/Users/you/.venv/bin/python -m pip install duckdb

Step 3: install duckdb into the interpreter VSCode selected

Call python -m pip against that interpreter, not a bare pip that may resolve to a different Python. This is the single most common fix.

bash
# Inside VSCode's integrated terminal, if the venv is activated:
python -m pip install duckdb

# Or explicitly against the interpreter path:
/Users/you/project/.venv/bin/python -m pip install duckdb

Step 4: if you meant to use the workspace venv, point VSCode at it

If duckdb is in a workspace venv but VSCode is on the system Python, switch the interpreter. Create the venv first if it does not exist.

bash
# Create a workspace venv (from the project root):
python3 -m venv .venv

# macOS / Linux:
source .venv/bin/activate
python -m pip install duckdb

# Windows PowerShell:
.venv\Scripts\Activate.ps1
python -m pip install duckdb

# Then in VSCode: Command Palette -> Python: Select Interpreter
# -> Enter interpreter path -> pick .venv/bin/python

Step 5: pin the interpreter in workspace settings so it does not drift

Once the correct interpreter is selected, write it into .vscode/settings.json. This keeps the choice stable across restarts and shared checkouts.

yaml
// .vscode/settings.json
{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
  "python.analysis.extraPaths": []
}

// Windows equivalent:
{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/Scripts/python.exe"
}

Step 6: for Poetry, Pipenv, or conda envs, select the env's interpreter

Tool-managed envs live outside the workspace. Ask the tool where its Python is, then feed that path to Python: Select Interpreter.

bash
# Poetry:
poetry env info --path
# Then point VSCode at <that-path>/bin/python

# Pipenv:
pipenv --venv
# Then <that-path>/bin/python

# conda (with env activated):
which python   # macOS / Linux
where python   # Windows

Step 7: if the variant is "could not be resolved from source", relax that specific rule

This diagnostic (reportMissingModuleSource) is separate from reportMissingImports and is safe to downgrade or disable. The import works at runtime; Pylance just cannot find source for stubs.

yaml
// .vscode/settings.json
{
  "python.analysis.diagnosticSeverityOverrides": {
    "reportMissingModuleSource": "none"
  }
}

Step 8: restart the Pylance language server if the squiggle is stale

After installing duckdb into the correct interpreter, Pylance sometimes needs a nudge before it re-indexes.

text
Command Palette -> Python: Restart Language Server

If that does not clear it:
Command Palette -> Developer: Reload Window

Step 9: check that a duckdb wheel exists for your Python version

If pip install duckdb finishes without actually installing anything, or prints a no-matching-distribution warning, your Python version is likely ahead of duckdb's release wheels. Downgrade Python or pin an earlier duckdb.

bash
python -m pip install --upgrade pip
python -m pip install duckdb -v

# If no wheel is available for your Python (e.g. very new 3.13/3.14):
# Option A: pin duckdb version:
python -m pip install "duckdb<1.4"

# Option B: use a supported Python (via pyenv, uv, conda):
pyenv install 3.12.7
pyenv local 3.12.7

Prevention

Commit a .vscode/settings.json with python.defaultInterpreterPath pointing at a workspace-relative .venv path. Anyone who clones the repo, creates the venv, and installs dependencies gets the same interpreter selection automatically.

Install packages with python -m pip install ..., not bare pip. The explicit form uses the interpreter you invoked, which removes the entire class of surprises where pip and python resolve to different Pythons.

For teams, use a lockfile-based workflow (Poetry, uv, pip-tools, or pipenv) and document the one command that produces the working environment. It removes the guesswork about which interpreter has which packages.

Debug DuckDB faster

1bench is a native GUI for DuckDB. Inspect queries, connections, and settings without leaving the app. See what's happening before you have to Google it.

Open DuckDB in 1bench