# Soda Python Libraries

## Installation

#### Requirements

To use Soda, you must have installed the following on your system.

* **Python 3.10, 3.11, or 3.12**.\
  To check your existing version, use the CLI command: `python --version` or `python3 --version`. If you have not already installed Python, consider using `pyenv` to manage multiple versions of Python in your environment.

{% hint style="info" %}
While Python 3.12 is the highest officially supported version, there are no known constraints preventing use of Python 3.13+.
{% endhint %}

* **Pip 21.0 or greater.**\
  To check your existing version, use the CLI command: `pip --version`
* **A Soda Cloud account**; see how to [sign up](https://docs.soda.io/quickstart#sign-up).

Best practice dictates that you **install the Soda CLI using a virtual environment**. If you haven't yet, in your command-line interface tool, create a virtual environment in the `.venv` directory using the commands below.

Soda recommends using [`uv`](https://github.com/astral-sh/uv):

```bash
uv venv .venv
source .venv/bin/activate
```

If you prefer the standard Python tooling (not using `uv`), depending on your version of Python, you may need to replace `python` with `python3` in the first command (or with the Python version you want your virtual environment to run, e.g. `py -3.11`):

```sh
python -m venv .venv
source .venv/bin/activate
```

#### Choose an installation flow

Before you install the Soda CLI, decide which installation flow applies to your environment and license type. The two flows available serve different purposes:

<table><thead><tr><th width="215.00006103515625">Use Case</th><th width="123.199951171875">Installation Flow</th><th>Description</th></tr></thead><tbody><tr><td>Executing data contracts with basic data quality checks on enterprise data sources. </td><td><a href="#public-pypi-installation-flow"><strong>Public PyPI</strong></a></td><td><p>Use this installation method if you’re just getting started.</p><p>The Public PyPI index hosts Soda Core packages for all supported data sources. </p></td></tr><tr><td>Same as above, plus: group by checks, reconciliation checks, migrating checks from v3 to v4, running checks on Oracle data, and capturing failed rows with the Diagnostics Warehouse. </td><td><a href="#private-pypi-installation-flow"><strong>Private PyPI</strong></a></td><td>Private PyPI repositories are region-specific and require authentication using your API key credentials. This method ensures secure access to licensed components, enterprise-only extensions, and region-compliant hosting.</td></tr></tbody></table>

{% hint style="info" %}
Different installations will support **different packages**. Learn more about which packages are supported in [public](#supported-packages) and [private](#supported-packages2) PyPI.
{% endhint %}

{% hint style="success" %}
**How to differentiate between free open-source Soda, and paid licensed Soda?**

**Soda V3**: package names included `core` if the package was free open-source. E.g.:

* `soda-core-postgres` (free open-source)
* `soda-postgres` (paid licensed Soda).

**Soda V4**: no differentiation using `core` in package names. Differentiation will be **based on the installation flows** listed above.
{% endhint %}

***

### Public PyPI installation flow

To use the open source Soda Core python packages, you must install them from the public Soda PyPi registry: `https://pypi.cloud.soda.io/simple` .

1. **Install the Soda Core package** for your data source. This gives you access to all the basic CLI functionality for working with contracts.

```bash
uv pip install -i https://pypi.cloud.soda.io/simple --pre -U "soda-postgres>4"
```

Replace `soda-postgres` with the appropriate package for your data source. See the [Data source reference for Soda Core](https://docs.soda.io/reference/data-source-reference-for-soda-core) for supported packages and configurations.

<i class="fa-octagon-check">:octagon-check:</i> Now you can connect to Soda Cloud.

#### Supported packages

* `soda-core`: "umbrella" package (does not include Diagnostics Warehouse)
* Data-source-specific packages: naming pattern is `soda-<datasource>` (e.g. `soda-postgres`, `soda-bigquery`, `soda-sparkdf`, etc.)

***

### Private PyPI installation flow

If you wish to use commercial extensions to the Soda Core python package, you must install them from one of the private Soda PyPi registries below. The private PyPI installation process adds an authentication layer and region-based repositories for license-based access control of **Team** and **Enterprise** customers.&#x20;

1. \[If not using `uv`] **Upgrade `pip`** inside your new virtual environment.

```sh
pip install --upgrade pip
```

2. **Choose the correct repository** based on your license and region.

<table><thead><tr><th width="197.59999084472656">License</th><th width="100">Soda Region</th><th>Repository URL</th></tr></thead><tbody><tr><td>Team<sup>1</sup></td><td>EU</td><td><a href="http://team.pypi.cloud.soda.io/">team.pypi.cloud.soda.io/</a></td></tr><tr><td>Team</td><td>US</td><td><a href="http://team.pypi.us.soda.io/">team.pypi.us.soda.io</a></td></tr><tr><td>Enterprise<sup>2</sup></td><td>EU</td><td><a href="http://enterprise.pypi.cloud.soda.io/">enterprise.pypi.cloud.soda.io</a></td></tr><tr><td>Enterprise</td><td>US</td><td><a href="http://enterprise.pypi.us.soda.io/">enterprise.pypi.us.soda.io/</a></td></tr></tbody></table>

<sup>1</sup> Team: Any license except "Trial" or "Enterprise" (see below)\ <sup>2</sup> Enterprise: one of `enterprise` , `enterprise_user_based` , `dataset_standard` , `premier` licenses.

3. **Set your credentials**.

```bash
export SODA_API_KEY_ID="your_key_id"
export SODA_API_KEY_SECRET="your_key_secret"
```

> See how to generate your own [API key values](https://docs.soda.io/reference/generate-api-keys).

4. Based on your license and region, **choose and execute one of the following commands**, **replacing** `soda>=4` with the package that you need to install.

{% tabs %}
{% tab title="Team EU" %}
{% code overflow="wrap" %}

```bash
uv pip install "soda>=4" --pre -i "https://${SODA_API_KEY_ID}:${SODA_API_KEY_SECRET}@team.pypi.cloud.soda.io" --extra-index-url=https://pypi.cloud.soda.io
```

{% endcode %}
{% endtab %}

{% tab title="Team US" %}
{% code overflow="wrap" %}

```bash
uv pip install "soda>=4" --pre -i "https://${SODA_API_KEY_ID}:${SODA_API_KEY_SECRET}@team.pypi.us.cloud.soda.io" --extra-index-url=https://pypi.cloud.soda.io
```

{% endcode %}
{% endtab %}

{% tab title="Enterprise EU" %}
{% code overflow="wrap" %}

```bash
uv pip install "soda>=4" --pre -i "https://${SODA_API_KEY_ID}:${SODA_API_KEY_SECRET}@enterprise.pypi.cloud.soda.io" --extra-index-url=https://pypi.cloud.soda.io
```

{% endcode %}
{% endtab %}

{% tab title="Enterprise US" %}
{% code overflow="wrap" %}

```bash
uv pip install "soda>=4" --pre -i "https://${SODA_API_KEY_ID}:${SODA_API_KEY_SECRET}@enterprise.pypi.us.cloud.soda.io" --extra-index-url=https://pypi.cloud.soda.io
```

{% endcode %}
{% endtab %}
{% endtabs %}

* `soda`: required for the contract generator (includes Diagnostics Warehouse)

  <pre class="language-sh" data-overflow="wrap"><code class="lang-sh">uv pip install "soda>=4" --pre -i "https://${SODA_API_KEY_ID}:${SODA_API_KEY_SECRET}@enterprise.pypi.cloud.soda.io" --extra-index-url=https://pypi.cloud.soda.io
  </code></pre>
* `soda-groupby`
* `soda-migration`
* `soda-reconciliation`
* `soda-oracle`

## Available extensions

The extensions you need to install depend on the **features** you want to use and your Soda subscription plan. The table below lists the supported features, the **required extension** for each one, and which plans include access.

{% if !(visitor.claims.plan === 'enterprise' || visitor.claims.plan === 'enterpriseUserBased') %}

| Feature                                                                                            | Required extension    | Available in plan   |
| -------------------------------------------------------------------------------------------------- | --------------------- | ------------------- |
| [Create contract](https://docs.soda.io/reference/cli-reference#create-a-contract)                  | `soda`                | Team and Enterprise |
| [Group by](https://docs.soda.io/reference/contract-language-reference#group-by-check)              | `soda-groupby`        | Team and Enterprise |
| [Diagnostics Warehouse](https://docs.soda.io/diagnostics-warehouse)                                | `soda`                | Team and Enterprise |
| [Reconciliation](https://docs.soda.io/reference/contract-language-reference/reconciliation-checks) | `soda-reconciliation` | Enterprise only     |
| Oracle connector                                                                                   | `soda-oracle`         | Enterprise only     |
| Dremio connector                                                                                   | `soda-dremio`         | Enterprise only     |
| {% endif %}                                                                                        |                       |                     |

{% if visitor.claims.plan === 'enterprise' || visitor.claims.plan === 'enterpriseUserBased' %}

| Feature                                                                                            | Required extension    | Available in plan   |
| -------------------------------------------------------------------------------------------------- | --------------------- | ------------------- |
| [Create contract](https://docs.soda.io/reference/cli-reference#create-a-contract)                  | `soda`                | Team and Enterprise |
| [Group by](https://docs.soda.io/reference/contract-language-reference#group-by-check)              | `soda-groupby`        | Team and Enterprise |
| [Diagnostics Warehouse ](https://docs.soda.io/deployment-options/broken-reference)                 | `soda`                | Team and Enterprise |
| [Reconciliation](https://docs.soda.io/reference/contract-language-reference/reconciliation-checks) | `soda-reconciliation` | Enterprise only     |
| Oracle connector                                                                                   | `soda-oracle`         | Enterprise only     |
| Dremio connector                                                                                   | `soda-dremio`         | Enterprise only     |
| {% endif %}                                                                                        |                       |                     |

<br>

***

{% if visitor.claims.plan === 'free' %}
{% hint style="success" %}
You are **logged in to Soda** and seeing the **Free license** documentation. Learn more about [documentation-access-and-licensing](https://docs.soda.io/reference/documentation-access-and-licensing "mention").
{% endhint %}
{% endif %}

{% if visitor.claims.plan === 'teams' %}
{% hint style="success" %}
You are **logged in to Soda** and seeing the **Team license** documentation. Learn more about [documentation-access-and-licensing](https://docs.soda.io/reference/documentation-access-and-licensing "mention").
{% endhint %}
{% endif %}

{% if visitor.claims.plan === 'enterprise' || visitor.claims.plan === 'enterpriseUserBased' %}
{% hint style="success" %}
You are **logged in to Soda** and seeing the **Enterprise license** documentation. Learn more about [documentation-access-and-licensing](https://docs.soda.io/reference/documentation-access-and-licensing "mention").
{% endhint %}
{% endif %}

{% if !(visitor.claims.plan === 'free' || visitor.claims.plan === 'teams' || visitor.claims.plan === 'enterprise' || visitor.claims.plan === 'enterpriseUserBased') %}
{% hint style="info" %}
You are **not logged in to Soda** and are viewing the default public documentation. Learn more about [documentation-access-and-licensing](https://docs.soda.io/reference/documentation-access-and-licensing "mention").
{% endhint %}
{% endif %}