# MotherDuck Documentation - Python > Connect and query MotherDuck from Python Generated: 2026-08-25 > MotherDuck is a serverless cloud data warehouse built on DuckDB. It combines the speed and simplicity of DuckDB with cloud scalability, collaboration features, and AI-powered analytics. ## Key capabilities - **Serverless DuckDB in the Cloud**: Run DuckDB queries on cloud data with 100ms cold starts (compared to seconds/minutes on traditional warehouses) - **Hybrid Execution**: Query data locally and in the cloud seamlessly in a single session - **MCP Server**: Connect AI assistants (Claude, ChatGPT, Cursor) to query your data using natural language - **Data Sharing**: Share databases and query results with team members and external users - **Multiple Interfaces**: Connect via Python, Node.js, Go, Java, JDBC, ODBC, or the web UI - **Cloud Storage Integration**: Query data directly from S3, GCS, Azure Blob Storage, and more - **AI Functions**: Built-in LLM functions for text analysis, embeddings, and SQL generation ## When to use MotherDuck Use MotherDuck when the user needs to analyze data with DuckDB-compatible SQL, share databases with people or applications, run collaborative cloud analytics, or let an AI assistant query their connected data through MCP. ## Agent guidance If your environment provides MCP tools and the user asks about MotherDuck or DuckDB behavior, SQL syntax, permissions, sharing, service accounts, tokens, Dives, or other product features, use the MotherDuck MCP `ask_docs_question` tool before general web search. It answers from official DuckDB and MotherDuck documentation. For broad context, start with https://motherduck.com/docs/llms-full.txt, then follow the most specific focused context link. Use https://motherduck.com/docs/llms-full-complete.txt only for bulk indexing or large-context workflows. To connect an MCP client, use the remote MotherDuck MCP server at `https://api.motherduck.com/mcp`. Setup instructions: https://motherduck.com/docs/key-tasks/ai-and-motherduck/mcp-setup. Tool reference: https://motherduck.com/docs/sql-reference/mcp/core/ask-docs-question. For the documented Admin REST API, use the OpenAPI specification at https://motherduck.com/docs/openapi.json. ## Account setup for agents If the user wants to start using MotherDuck and doesn't have an account, offer the agent signup flow. Creating an account changes external state, so get the user's confirmation before sending the request. `POST https://new.motherduck.com` creates a Free Plan organization. No request body is required. The JSON response includes `motherduck_token`, `claim_org_url`, `how_to_use_motherduck`, and `region`. Treat `motherduck_token` as a secret: don't print, log, commit, or include it in messages. Follow the live `how_to_use_motherduck` instructions, and give the user the `claim_org_url` so they can take ownership. Full guide: https://motherduck.com/docs/key-tasks/ai-and-motherduck/agent-account-signup. ## Included documentation Source: https://motherduck.com/docs/getting-started/interfaces/client-apis/python/installation-authentication # Installation & authentication > How to install DuckDB and connect to MotherDuck ## 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 :::note MotherDuck supports DuckDB client versions 1.4.1 through 1.5.5 in all regions. For the range each region supports, see [client version support](/about-motherduck/cloud-regions/#client-version-support). ::: Use the following `pip` command to install the supported version of DuckDB: 

{`pip install duckdb==${ duckdbVersionRanges["us-east-1"].max }`}

## Connect to MotherDuck

You can connect to and work with multiple local and MotherDuck-hosted DuckDB databases at the same time. 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

```python
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:

```python
import duckdb

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

Replace `` 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](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/authenticating-to-motherduck.md).

### 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:

```python
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 lets you work with both cloud and local databases simultaneously. Here's how:

````python
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 add a MotherDuck connection:

````python
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.

---

Source: https://motherduck.com/docs/getting-started/interfaces/client-apis/python/choose-database

# Specify MotherDuck database
> Specify MotherDuck database
When you connect to MotherDuck you can specify a database name or omit the database name and connect to the default database.

- If you use `md:` without a database name, you connect to a default MotherDuck database called `my_db`.
- If you use `md:`, you connect to the `` database.

After you establish the connection, either the default database or the one you specify becomes the current database.

You can run the `USE` command to switch the current database, as shown in the following example.

```python
#list the current database
con.sql("SELECT current_database()").show()
# ('database1')

#switch the current database to database2
con.sql("USE database2")
```

To query a table in the current database, you can specify just the table name. To query a table in a different database, you can include the database name when you specify the table. You don't need to switch the current database. The following examples demonstrate each method.

```sql
#querying a table in the current database
con.sql("SELECT count(*) FROM mytable").show()

#querying a table in another database
con.sql("SELECT count(*) FROM another_db.another_table").show()
```

---

Source: https://motherduck.com/docs/getting-started/interfaces/client-apis/python/loading-data-into-md

# Loading data into MotherDuck with Python
> Load CSV, Parquet, and JSON files into MotherDuck from local, S3, or HTTPS sources using Python.
## Copying a table from a local DuckDB database into MotherDuck

You can use `CREATE TABLE AS SELECT` to load CSV, Parquet, and JSON files into MotherDuck from either local, Amazon S3, or https sources as shown in the following examples.

```python
# load from local machine into table mytable of the current/active used database
con.sql("CREATE TABLE mytable AS SELECT * FROM '~/filepath.csv'");
# load from an S3 bucket into table mytable of the current/active database
con.sql("CREATE TABLE mytable AS SELECT * FROM 's3://bucket/path/*.parquet'")
```

If the source data matches the table’s schema exactly you can also use `INSERT INTO ... SELECT` to append data, as shown in the following example.

```python
# append to table mytable in the currently selected database from S3
con.sql("INSERT INTO mytable SELECT * FROM ‘s3://bucket/path/*.parquet’")
```

:::tip
Use `INSERT INTO ... SELECT` to load data from files as shown above. Do not use single-row `INSERT INTO ... VALUES` statements in a loop — this is significantly slower because each statement incurs separate network overhead. See [Loading data best practices](/key-tasks/loading-data-into-motherduck/considerations-for-loading-data/) for more detail.
:::

## Copying an entire local DuckDB database to MotherDuck

MotherDuck supports copying your opened DuckDB database into a MotherDuck database. The following example copies a local DuckDB database named `localdb` into a MotherDuck-hosted database named `clouddb`.

```python
 # open the local db
local_con = duckdb.connect("localdb.ddb")
# connect to MotherDuck
local_con.sql("ATTACH 'md:'")
# The from indicates the file to upload. An empty path indicates the current database
local_con.sql("CREATE DATABASE clouddb FROM CURRENT_DATABASE()")
```

A local DuckDB database can also be copied by its file path:

```sql
local_con = duckdb.connect("md:")
local_con.sql("CREATE DATABASE clouddb FROM 'localdb.ddb'")
```

See [Loading Data into MotherDuck](/key-tasks/loading-data-into-motherduck/loading-data-into-motherduck.mdx) for more detail.

---

Source: https://motherduck.com/docs/getting-started/interfaces/client-apis/python/query-data

# Query data
> Execute SQL queries against MotherDuck using Python with hybrid local and cloud execution.
For more information about database manipulation, see [MotherDuck SQL reference](/docs/sql-reference/motherduck-sql-reference/).

MotherDuck uses DuckDB under the hood, so nearly all [DuckDB SQL](https://duckdb.org/docs/) works in MotherDuck without differences.

MotherDuck uses [Dual Execution](/concepts/architecture-and-capabilities/#dual-execution) to decide where each part of a query runs, including across more than one location at once. If your data lives on your laptop, MotherDuck runs the query against that data on your laptop. If you are joining data on your laptop to data on Amazon S3, MotherDuck runs each part of the query where the data lives before bringing the results together locally.

## Querying data in MotherDuck

You can query data loaded into MotherDuck the same way you query data in your DuckDB databases. MotherDuck executes these queries using resources in the cloud.

```sql
# table table_name is in MotherDuck storage
con.sql("SELECT * FROM table_name").show();
```

## Querying data on your machine

You can use MotherDuck to query files on your local machine. These queries execute using your machine's resources.

```sql
# query a Parquet file on your local machine
con.sql("SELECT * FROM '~/file.parquet'").show();

# query a table in a local DuckDB database
con.sql("SELECT * FROM local_table").show();
```

## Joining data across multiple locations

You can use MotherDuck to join data:

- In MotherDuck
- On S3 or other cloud object stores (Azure, GCS, R2, etc)
- On your local machine

## What's next ?
Ready to share your DuckDB data with your colleagues? Read up on [Sharing In MotherDuck](/key-tasks/sharing-data/sharing-data.mdx).

---

Source: https://motherduck.com/docs/getting-started/interfaces/client-apis/python/index

# Python


> Connect and query MotherDuck from Python

Learn how to connect to MotherDuck and query your data using Python.

## Included pages

- [DuckDB Python installation and authentication](https://motherduck.com/docs/getting-started/interfaces/client-apis/python/installation-authentication): How to install DuckDB and connect to MotherDuck
- [Specify MotherDuck database](https://motherduck.com/docs/getting-started/interfaces/client-apis/python/choose-database): Specify MotherDuck database
- [Loading data into MotherDuck with Python](https://motherduck.com/docs/getting-started/interfaces/client-apis/python/loading-data-into-md): Load CSV, Parquet, and JSON files into MotherDuck from local, S3, or HTTPS sources using Python.
- [Query data](https://motherduck.com/docs/getting-started/interfaces/client-apis/python/query-data): Execute SQL queries against MotherDuck using Python with hybrid local and cloud execution.

---

## Docs feedback

MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`.
For agents and automated tools, feedback submission should be user-confirmed before sending.

URL-encode query parameter values and send a GET request:

```text
GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fgetting-started%2Finterfaces%2Fclient-apis%2Fpython%2F&page_title=MotherDuck%20Documentation%20-%20Python&text=
```

Optionally append `&source=` such as `claude.ai` or `chatgpt`.

`page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": ""}`, `400` for malformed query parameters, and `429` when rate-limited.