Install & Compatibility
Where this runs
tested against v1.1.2 · 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
py 3.9
✕ build_error
✕ build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DataContract
✓ from datacontract.data_contract import DataContract
This quickstart demonstrates how to use `datacontract-cli` as a Python library to load a data contract from a YAML file and execute its defined schema and quality tests. It simulates a simple local data source. For actual data sources like S3 or BigQuery, ensure relevant environment variables are set for credentials, as shown in comments.
import os
from datacontract.data_contract import DataContract
# Simulate a datacontract.yaml file content
datacontract_yaml_content = '''
dataContractSpecification: 1.2.0
id: urn:datacontract:example:test-contract
info:
title: Example Test Contract
version: 1.0.0
owner: Data Team
servers:
local_file:
type: local
path: ./data/{model}.csv
format: csv
delimiter: ','
models:
my_data:
description: A simple dataset for testing.
fields:
id:
type: string
primaryKey: true
name:
type: string
value:
type: integer
quality:
- type: sql
description: 'All values should be positive.'
query: |
SELECT *
FROM my_data
WHERE value <= 0
'''
# Create a dummy data file for the test
with open('data_my_data.csv', 'w') as f:
f.write('id,name,value\n')
f.write('1,Alice,10\n')
f.write('2,Bob,20\n')
# Write the data contract to a temporary file
with open('datacontract.yaml', 'w') as f:
f.write(datacontract_yaml_content)
# Environment variables for credentials are often required for real data sources.
# For local testing, they might not be strictly needed depending on the 'server' configuration.
# os.environ['DATACONTRACT_S3_ACCESS_KEY_ID'] = os.environ.get('DATACONTRACT_S3_ACCESS_KEY_ID', '')
# os.environ['DATACONTRACT_S3_SECRET_ACCESS_KEY'] = os.environ.get('DATACONTRACT_S3_SECRET_ACCESS_KEY', '')
try:
data_contract = DataContract(data_contract_file="datacontract.yaml")
run_results = data_contract.test()
if run_results.has_passed():
print("Data contract tests passed successfully.")
else:
print("Data contract tests failed.")
print(run_results.to_json())
except Exception as e:
print(f"An error occurred: {e}")
finally:
# Clean up dummy files
os.remove('datacontract.yaml')
os.remove('data_my_data.csv')
datacontract --version
Debug
Known issues
breakingThe project migrated from Go to Python, introducing breaking changes for users relying on the Go CLI. The Go version has been forked and is no longer actively developed by the main project. Users previously relying on the Go version for programmatic use need to switch to the Python library.fixMigrate your usage to the Python CLI or library. If absolutely necessary to use the Go version, find its forked repository. Review the migration guide for specific syntax changes.
affects: Before 0.10.x (Go versions) to 0.10.x+ (Python versions)
breakingThe internal data model transitioned from 'Data Contract Specification' to 'Open Data Contract Standard (ODCS) v3.1.0' as the default. This is a major change, and not all features of the old specification are supported in ODCS. The Data Contract Specification is now deprecated.fixMigrate existing data contract YAML files to the Open Data Contract Standard (ODCS). A migration instruction is available in the documentation. Be aware of unsupported features like internal `$ref` definitions or lineage.
affects: 0.11.0 and later (existing Data Contract Specification files are supported in 0.11.x until end of 2026)
gotchaCredentials for connecting to data sources (e.g., S3, BigQuery, PostgreSQL) are typically provided via environment variables and should not be hardcoded in your `datacontract.yaml` or version control. Each server type has specific environment variable naming conventions (e.g., `DATACONTRACT_S3_ACCESS_KEY_ID`).fixAlways use environment variables or a secure secret management system for sensitive credentials. Consult the documentation for the specific environment variables required for your data source type.
affects: All versions
gotchaThe library requires Python versions >=3.10 and <3.13. Using unsupported Python versions may lead to installation failures or runtime issues.fixEnsure your environment uses a compatible Python version (3.10, 3.11, or 3.12). Consider using virtual environments (e.g., `venv`, `conda`) or `uv` to manage Python versions and dependencies.
affects: All versions
gotchaSpecific internal dependencies, such as `DuckDB`, may have version restrictions. For example, version 0.11.3 fixed a dependency issue by restricting `DuckDB` to `<1.4.0`. Attempting to use a newer, incompatible version of such internal dependencies can cause failures.fixRely on `datacontract-cli`'s own dependency management (e.g., by installing with `pip install datacontract-cli[all]`) to ensure compatible versions of its internal engines. If issues arise, check the `datacontract-cli` changelog for specific dependency version pins.
affects: May vary by `datacontract-cli` patch version
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'datacontract'
The 'datacontract-cli' package is not installed or not properly installed in the Python environment.
fixInstall the package using 'pip install datacontract-cli'.
AttributeError: module 'datacontract' has no attribute 'test'
Attempting to call a non-existent 'test' attribute on the 'datacontract' module.
fixUse the correct command-line interface by running 'datacontract test' in the terminal.
datacontract: command not found
The 'datacontract-cli' is not installed or not added to the system's PATH.
fixEnsure 'datacontract-cli' is installed and the installation directory is included in the system's PATH.
Error: Invalid data contract file format
The provided data contract YAML file is incorrectly formatted or contains syntax errors.
fixValidate the YAML file for correct syntax and structure according to the Data Contract Specification.
ConnectionError: Failed to connect to data source
The CLI is unable to establish a connection to the specified data source, possibly due to incorrect credentials or network issues.
fixVerify the data source connection details, including host, port, and credentials, and ensure network connectivity.
Upgrade
Version history
1.1.2latest on PyPI · released Aug 26, 2026
Audit
Dependencies
soda-coreoptionalUsed internally for data quality testing.
fastjsonschemaoptionalUsed internally for schema validation.
duckdboptionalUsed internally for native connections and testing, often with a version restriction.
datacontract-cli[<db_type>]optionalNumerous optional extras exist for specific database connectors (e.g., athena, bigquery, snowflake, postgres, s3). The '[all]' extra installs all of them.