⌘+k ctrl+k
1.3 (stable)
Search Shortcut cmd + k | ctrl + k
Known Python Issues

Troubleshooting

Running EXPLAIN Renders Newlines

In Python, the output of the EXPLAIN statement contains hard line breaks (\n):

In [1]: import duckdb
   ...: duckdb.sql("EXPLAIN SELECT 42 AS x")

Out[1]:
┌───────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│  explain_key  │                                                   explain_value                                                   │
│    varchar    │                                                      varchar                                                      │
├───────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ physical_plan │ ┌───────────────────────────┐\n│         PROJECTION        │\n│   ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─   │\n│             x   …  │
└───────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

To work around this, print the output of the explain() function:

In [2]: print(duckdb.sql("SELECT 42 AS x").explain())

Out[2]:
┌───────────────────────────┐
│         PROJECTION        │
│   ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─   │
│             x             │
└─────────────┬─────────────┘
┌─────────────┴─────────────┐
│         DUMMY_SCAN        │
└───────────────────────────┘

Please also check out the Jupyter guide for tips on using Jupyter with JupySQL.

Crashes and Errors on Windos

When importing DuckDB on Windows, the Python runtime may crash or return an error upon import or first use:

import duckdb

duckdb.sql("...")

ImportError: DLL load failed while importing duckdb: The specified module could not be found.

Windows fatal exception: access violation

Current thread 0x0000311c (most recent call first):
  File "<stdin>", line 1 in <module>

Process finished with exit code -1073741819 (0xC0000005)

The problem is likely caused by using an outdated Microsoft Visual C++ (MSVC) Redistributable package. The solution is to install the latest MSVC Redistributable package. Alternatively, you can instruct pip to compile the package from source as follows:

python3 -m pip install duckdb --no-binary duckdb

Known Issues

Unfortunately there are some issues that are either beyond our control or are very elusive / hard to track down. Below is a list of these issues that you might have to be aware of, depending on your workflow.

Numpy Import Multithreading

When making use of multi threading and fetching results either directly as Numpy arrays or indirectly through a Pandas DataFrame, it might be necessary to ensure that numpy.core.multiarray is imported. If this module has not been imported from the main thread, and a different thread during execution attempts to import it this causes either a deadlock or a crash.

To avoid this, it's recommended to import numpy.core.multiarray before starting up threads.

DESCRIBE and SUMMARIZE Return Empty Tables in Jupyter

The DESCRIBE and SUMMARIZE statements return an empty table:

%sql
CREATE OR REPLACE TABLE tbl AS (SELECT 42 AS x);
DESCRIBE tbl;

To work around this, wrap them into a subquery:

%sql
CREATE OR REPLACE TABLE tbl AS (SELECT 42 AS x);
FROM (DESCRIBE tbl);

Protobuf Error for JupySQL in IPython

Loading the JupySQL extension in IPython fails:

In [1]: %load_ext sql

ImportError: cannot import name 'builder' from 'google.protobuf.internal' (unknown location)

The solution is to fix the protobuf package. This may require uninstalling conflicting packages, e.g.:

%pip uninstall tensorflow
%pip install protobuf
About this page