Soda Python Libraries

This page describes how to install the Soda Python packages, which are required for running Soda scans via the CLI or Python API.

Installation

Requirements

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

• Python 3.9, 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.

While Python 3.12 is the highest officially supported version, there are no known constraints preventing use of Python 3.13+.

• 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.

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. 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).

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:

Use Case	Installation Flow	Description
Executing data contracts with basic data quality checks on enterprise data sources.	Public PyPI	Use this installation method if you’re just getting started. The Public PyPI index hosts Soda Core packages for all supported data sources.
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.	Private PyPI	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.

Different installations will support different packages. Learn more about which packages are supported in public and private PyPI.

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.

---

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.

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 for supported packages and configurations.

Now you can connect to Soda Cloud.

Supported packages

• soda: "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.

1. Upgrade pip inside your new virtual environment.

pip install --upgrade pip

1. Choose the correct repository based on your license and region.

License	Soda Region	Repository URL
Team1	EU	team.pypi.cloud.soda.io/
Team	US	team.pypi.us.soda.io
Enterprise2	EU	enterprise.pypi.cloud.soda.io
Enterprise	US	enterprise.pypi.us.soda.io/

¹ Team: Any license except "Trial" or "Enterprise" (see below) ² Enterprise: one of enterprise , enterprise_user_based , dataset_standard , premier licenses.

1. Set your credentials.

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.

1. 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.

Team EU

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

Team US

Enterprise EU

Enterprise US

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

  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

• 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.

Feature	Required extension	Available in plan
Create contract	soda	Team and Enterprise
Group by	soda-groupby	Team and Enterprise
Diagnostics Warehouse	soda	Team and Enterprise
Reconciliation	soda-reconciliation	Enterprise only
Oracle connector	soda-oracle	Enterprise only
Dremio connector	soda-dremio	Enterprise only

---

You are not logged in to Soda and are viewing the default public documentation. Learn more about Documentation access & licensing.