fix/duckdb/has-no-attribute-connect
DuckDB error

module 'duckdb' has no attribute 'connect'

Updated Aug 27, 20264-min read
TL;DR

Python is not importing the real DuckDB package. Almost always because a file named duckdb.py sits next to your script and shadows the installed package, or because pip installed DuckDB into a different interpreter than the one running your code.

  • ·You have a file called duckdb.py (or a folder named duckdb/) in the same directory as the script you are running
  • ·A leftover __pycache__/duckdb.cpython-*.pyc from an old duckdb.py still shadows the real package
  • ·pip installed duckdb into a different Python than the one you are running (system Python vs venv, python vs python3)
  • ·You installed duckdb-engine (the SQLAlchemy adapter) instead of duckdb
  • ·The install was interrupted and the package is partially unpacked
CHECK FIRSTRun `python -c "import duckdb; print(duckdb.__file__)"`. If the path points at your own project instead of site-packages, that file is shadowing DuckDB.

What you're seeing

The traceback fires the moment your code calls duckdb.connect(). Python found something called duckdb, imported it, and did not find a connect attribute on it.

text
Traceback (most recent call last):
  File "script.py", line 3, in <module>
    con = duckdb.connect()
          ^^^^^^^^^^^^^^
AttributeError: module 'duckdb' has no attribute 'connect'

# Variant when a local file also imports duckdb, causing partial init:
AttributeError: partially initialized module 'duckdb' has no attribute 'connect' (most likely due to a circular import)
Also seen as: AttributeError: module 'duckdb' has no attribute 'connect', partially initialized module 'duckdb' has no attribute 'connect', duckdb has no attribute connect, duckdb module has no attribute connect

What's causing this

Ranked most-likely first.

  1. 1

    A local duckdb.py is shadowing the installed package

    Python searches the script's own directory before site-packages. If you have a file called duckdb.py in the same folder (a common accident when learning the library and naming a demo script after it), import duckdb loads your file, not the real package. Your file has no connect function, so the attribute lookup fails.

  2. 2

    A cached .pyc file from an old duckdb.py is still around

    You deleted the offending duckdb.py but left __pycache__/duckdb.cpython-311.pyc behind. Python will still import the cached bytecode ahead of the real package until the cache is cleared.

  3. 3

    pip installed DuckDB into a different interpreter

    You ran `pip install duckdb` but your script runs under a different Python. Common on macOS and Linux where `python` is Python 2 or the system Python and `python3` is a venv, or where an IDE picks a different interpreter than your terminal. The import silently succeeds because some other duckdb-shaped thing is on the path, but the real package is not installed for this interpreter.

  4. 4

    You installed duckdb-engine, not duckdb

    `pip install duckdb-engine` installs the SQLAlchemy dialect, which imports under the name sqlalchemy_duckdb (or similar) and has no top-level connect function. Running import duckdb after installing only duckdb-engine can also pull in a stub with no connect attribute.

  5. 5

    The install is partial or corrupted

    A killed pip install, a failed wheel download, or a mixed-version install can leave duckdb/__init__.py present but the compiled C extension missing. Import succeeds but nothing useful is exported.

  6. 6

    Circular import in your own module

    If your module is called duckdb and it does import duckdb at the top, Python begins initializing your module, tries to import itself again, and hands back a partially initialized module object. That module has no connect attribute because your file has not finished executing.

How to fix it

Step 1: check which file Python is actually importing

Ask Python where duckdb came from. If the path is anywhere inside your project instead of site-packages, that file is the problem.

bash
python -c "import duckdb; print(duckdb.__file__)"

# Healthy output looks like:
# /Users/you/.venv/lib/python3.11/site-packages/duckdb/__init__.py

# Broken output looks like:
# /Users/you/project/duckdb.py

Step 2: rename or delete the local duckdb.py

If step 1 pointed at a file in your project, rename it to something that is not the name of a package you are using. `demo.py`, `try_duckdb.py`, and `main.py` all work.

bash
mv duckdb.py demo.py

# Then clear the bytecode cache so an old .pyc does not keep shadowing:
rm -rf __pycache__

Step 3: confirm duckdb is installed for the right interpreter

Match the Python that runs your script with the Python that installed duckdb. `sys.executable` shows the current interpreter; `python -m pip list` shows what is installed for it.

bash
# Which Python runs your script:
python -c "import sys; print(sys.executable)"

# Install duckdb into THAT Python, not whichever pip is on PATH:
python -m pip install duckdb

# Verify:
python -m pip show duckdb

Step 4: reinstall from scratch

If the install is partial or duckdb-engine got in the way, uninstall both and reinstall the real package. Use --force-reinstall to overwrite any half-unpacked files.

bash
python -m pip uninstall -y duckdb duckdb-engine
python -m pip install --force-reinstall duckdb

# Sanity check:
python -c "import duckdb; print(duckdb.__version__); print(duckdb.connect().sql('SELECT 42').fetchone())"

Step 5: if you are inside a virtualenv, make sure it is activated

Installing into a venv and then running the script from a terminal where the venv is not activated is the same failure as step 3, just with a friendlier fix. Activate the venv and reinstall if needed.

bash
# macOS / Linux:
source .venv/bin/activate

# Windows PowerShell:
.venv\Scripts\Activate.ps1

# Then:
python -m pip install duckdb
python -c "import duckdb; print(duckdb.__file__)"

Step 6: rename any of your own modules called duckdb

If your codebase has its own module or package called duckdb (an internal wrapper, for example), rename it. Even without a same-directory conflict, having your own duckdb somewhere on sys.path guarantees the wrong import wins on any interpreter where it lands earlier in the search order.

python
# Instead of:
# your_project/duckdb.py

# Rename to a distinct namespace:
# your_project/duckdb_helpers.py

# And import it under its own name:
from your_project import duckdb_helpers
con = duckdb_helpers.get_connection()

Prevention

Never name a script or module after a library you are about to import. This bites every Python package (requests.py, email.py, json.py) and the fix is always the same rename. Pick a name that describes what your file does, not what it imports.

Prefer `python -m pip install <package>` over bare `pip install <package>`. The `python -m` form guarantees the install lands in the same interpreter your script runs under, which sidesteps the entire class of wrong-interpreter installs.

Work inside a venv per project and activate it before running or installing anything. When there is only one Python on PATH inside the shell, the wrong-interpreter failure mode disappears.

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