Skip to main content

Installation & authentication

Prerequisites​

MotherDuck Python supports the following operating systems:

  • Linux (x64, glibc v2.31+, equivalent to ubuntu v20.04+)
  • Mac OSX 11+ (M1/ARM or x64)
  • Python 3.4 or later Please let us know if your configuration is unsupported.

Installing DuckDB​

caution

MotherDuck currently supports DuckDB 1.1.3 and it is compatible with any client version 0.10.2 through 1.1.3

Use the following pip command to install the supported version of DuckDB:

pip install duckdb==1.1.3

Connect to MotherDuck​

You can connect to and work with multiple local and MotherDuck-hosted DuckDB databases at the same time. Currently, the connection syntax varies depending on how you’re opening local DuckDB and MotherDuck.

Authenticating to MotherDuck​

You can authenticate to MotherDuck using either browser-based authentication or an access token. Here are examples of both methods:

Using browser-based authentication​

import duckdb

# connect to MotherDuck using 'md:' or 'motherduck:'
con = duckdb.connect('md:')

When you run this code:

  1. A URL and a code will be displayed in your terminal.
  2. Your default web browser will automatically open to the URL.
  3. You'll see a confirmation request to approve the connection.
  4. Once, approved, if you're not already logged in to MotherDuck, you'll be prompted to do so.
  5. Finally, you can close the browser tab and return to your Python environment.

This method is convenient for interactive sessions and doesn't require managing access tokens.

Using an access token​

For automated scripts or environments where browser-based auth isn't suitable, you can use an access token:

import duckdb

# Initiate a MotherDuck connection using an access token
con = duckdb.connect('md:?motherduck_token=<your_access_token>')

Replace <your_access_token> with an actual token generated from the MotherDuck UI.

To learn more about creating and managing access tokens, as well as other authentication options, see our guide on Authenticating to MotherDuck.

Connecting to MotherDuck​

Once you've authenticated, you can connect to MotherDuck and start working with your data. Let's look at a few common scenarios.

Connecting directly to MotherDuck​

Here's how to connect to MotherDuck and run a simple query:

import duckdb

# Connect to MotherDuck via browser-based authentication
con = duckdb.connect('md:my_db')

# Run a query to verify the connection
con.sql("SHOW DATABASES").show()
tip

When connecting to MotherDuck, you need to specify a database name (like my_db in the example). If you're a new user, a default database called my_db is automatically created when your account is first set up. You can query any table in your connected database by just using its name. To switch databases, use the USE command.

Working with both MotherDuck and local databases​

MotherDuck allows you to work with both cloud and local databases simultaneously. Here's how:

import duckdb

# Connect to MotherDuck first, specifying a database
con = duckdb.connect('md:my_db')

# Then attach local DuckDB databases
con.sql("ATTACH 'local_database1.duckdb'")
con.sql("ATTACH 'local_database2.duckdb'")

# List all connected databases
con.sql("SHOW DATABASES").show()

Adding MotherDuck to an existing local connection​

If you're already working with a local DuckDB database, you can easily add a MotherDuck connection:

import duckdb

# Start with a local DuckDB database
local_con = duckdb.connect('local_database.duckdb')

# Add a MotherDuck connection, specifying a database
local_con.sql("ATTACH 'md:my_db'")

This is another approach to give you the flexibility to work with both local and cloud data in the same session.