---
sidebar_position: 1
title: "DuckDB Python Client: Installation & authentication"
sidebar_label: Installation & authentication
description: How to install DuckDB and connect to MotherDuck
hide_title: true
---
import Versions, { duckdbVersionRanges } from '@site/src/components/Versions';

# 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

:::note

MotherDuck currently supports DuckDB <Versions region="us-east-1" bound="max" />. In **US East (N. Virginia) -** `us-east-1`, MotherDuck is compatible with client versions <Versions region="us-east-1" bound="min" /> through <Versions region="us-east-1" bound="max" />. In **Europe (Frankfurt) -** `eu-central-1`, MotherDuck supports client versions <Versions region="eu-central-1" bound="min" /> through <Versions region="eu-central-1" bound="max" />.
:::

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

<pre><code>
{`pip install duckdb==${ duckdbVersionRanges["us-east-1"].max }`}
</code></pre>

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

```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=<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](/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 allows you to 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 easily 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.