Install & Compatibility
Where this runs
tested against v4.22.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 57.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 6.7s · import 0.000s · 58MB
55MB installed
● package 55MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Scan
✓ from soda_core.scan import Scan
✗ from soda_core.scan import Scan
This quickstart demonstrates how to run a programmatic Soda Core scan against a local CSV file. It defines the data source and SodaCL checks as strings, executes the scan, and prints a summary of the results. If you don't have it, install `pandas` (`pip install pandas`) for the CSV creation portion of this example.
import os
import pandas as pd
from soda.scan import Scan
# Create a dummy CSV file for the example
csv_filename = "sample_data.csv"
df = pd.DataFrame({
'id': [1, 2, 3, 4, 5],
'value': ['A', 'B', 'C', 'D', 'E'],
'status': ['active', 'inactive', 'active', 'active', None]
})
df.to_csv(csv_filename, index=False)
# Define the data source configuration as a string
data_source_config = f"""
data_source my_csv_source:
type: local_system
file_system:
type: local
path: {os.getcwd()}
"""
# Define SodaCL checks as a string
sodacl_checks = f"""
checks for {csv_filename}:
- row_count > 0
- missing_count(status) = 1
- duplicate_count(id) = 0
"""
# Run the Soda Core scan programmatically
scan = Scan()
scan.set_verbose(True) # Optional: for more detailed output
scan.add_configuration_yaml_str(data_source_config)
scan.add_sodacl_yaml_str(sodacl_checks)
scan.set_data_source_name("my_csv_source") # Must match the name in data_source_config
scan.execute_scan()
print("\n--- Scan Results ---")
if scan.has_failures():
print("Scan completed with failures.")
else:
print("Scan completed successfully.")
# Clean up the dummy CSV file
os.remove(csv_filename)
soda --version
Debug
Known issues
breakingMajor API changes occurred in Soda Core 4.0.0. The `Scan` object's methods, configuration file naming, and SodaCL syntax were revised. For example, `scan.set_scan_definition_name()` and `scan.add_sodacl_yaml_file()` from 3.x were replaced by methods like `scan.set_data_source_name()` and `scan.add_check_yaml_file()` or `add_sodacl_yaml_str()`.fixRefer to the official Soda Core 4.x documentation for updated API usage and SodaCL syntax. Specifically, review migration guides for changes in `Scan` object methods and configuration file structures (e.g., `configuration.yml` to `data_source.yml`).
affects: >=4.0.0 (when migrating from <4.0.0)
gotchaSoda Core itself does not include database drivers. You must install specific `soda-core-<data-source>` packages (e.g., `soda-core-postgres`, `soda-core-bigquery`, `soda-core-snowflake`) separately for the data sources you intend to scan. Failure to do so will result in connection errors.fixInstall the appropriate `soda-core-<data-source>` package for your database, e.g., `pip install soda-core-postgres`.
affects: All versions
gotchaWhen running `soda scan` from the CLI without explicitly specifying configuration files (e.g., `-d data_source.yml -c checks.yml`), Soda Core automatically looks for `data_source.yml` and `checks.yml` (or `configuration.yml` in older versions) in the current working directory. This can lead to unexpected scans or configuration mismatches.fixAlways explicitly specify your configuration and check files using the `-d` and `-c` CLI arguments, or use programmatic methods like `add_configuration_yaml_str()` and `add_sodacl_yaml_str()` to ensure predictable behavior.
affects: All versions
Upgrade
Version history
4.22.0latest on PyPI · released Aug 25, 2026
Audit
Dependencies
soda-core-postgresoptionalRequired for scanning PostgreSQL data sources.
soda-core-bigqueryoptionalRequired for scanning Google BigQuery data sources.
soda-core-snowflakeoptionalRequired for scanning Snowflake data sources.
pandasoptionalUsed in the quickstart example to create a dummy CSV file.