Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
The `elementary-data` library's primary function is accessed via its command-line interface (`edr`), which generates data observability reports and sends alerts based on dbt project artifacts. This quickstart assumes you have an active dbt project with the Elementary dbt package configured and run. The `edr report` command will then query your data warehouse (via your dbt profiles) and generate a comprehensive HTML report.
# 1. Install the Elementary dbt package (in your dbt project's packages.yml):
# packages:
# - package: elementary-data/elementary
# version: 0.23.0 # Use the latest version
# 2. Add configuration to your dbt_project.yml (example):
# models:
# elementary:
# +schema: "elementary"
# 3. Install dbt dependencies and build Elementary models:
# dbt deps
# dbt run --select elementary
# dbt test
# 4. Install the Elementary CLI:
pip install elementary-data
# 5. Ensure your dbt profiles.yml is configured with an 'elementary' profile
# (see Elementary docs for details, typically ~/.dbt/profiles.yml)
# 6. Generate the data observability report:
# The report will be saved as an HTML file in 'target/elementary_report.html'
edr report --project-dir $(pwd)
# Or to monitor and send alerts:
# edr monitor --slack-token $SLACK_TOKEN --slack-channel '#data-alerts'
edr --version
Debug
Known issues
breakingThe `elementary-data` Python CLI works in conjunction with the `elementary-data/elementary` dbt package. Frequent updates to the dbt package can introduce incompatibilities if the CLI and dbt package versions are not aligned. Always refer to the official documentation for recommended version pairings.fixEnsure both the `elementary-data` Python library and the `elementary-data/elementary` dbt package are updated to compatible versions as recommended in Elementary's documentation. Regularly check release notes for specific version compatibility information.
affects: All versions, due to inter-package dependencies
deprecatedIn version 0.23.0, `datetime.utcnow()` was replaced with `datetime.now(tz=timezone.utc)` for compliance with Python's best practices regarding timezone-aware datetimes. Code directly interacting with Elementary's internal datetime handling might need updating.fixMigrate any custom code that interacts with `datetime.utcnow()` to `datetime.now(tz=timezone.utc)` to ensure timezone-aware operations and avoid future deprecation warnings.
affects: >=0.23.0
gotchaWhile v0.19.2 addressed a specific backwards compatibility issue with Pydantic, broader Pydantic major version transitions (e.g., v1 to v2) can still cause issues if other libraries in your environment have conflicting Pydantic versions. This can lead to unexpected runtime errors.fixKeep `elementary-data` updated to the latest version to benefit from Pydantic compatibility fixes. When encountering Pydantic errors, check if other installed libraries have conflicting Pydantic version requirements. Consider using tools like `pipdeptree` or `pydantic-compat` for complex dependency environments.
affects: <0.19.2, and potentially any version in environments with mixed Pydantic dependencies.
gotchaElementary updated its internal dbt usage in v0.20.0 to remove the deprecated `-m` flag. Users running older versions of `elementary-data` with newer `dbt` versions might experience unexpected behavior or errors related to dbt command execution.fixUpgrade `elementary-data` to version 0.20.0 or higher to ensure compatibility with updated dbt command structures.
affects: <0.20.0 when used with newer dbt versions
gotchaThe `edr` CLI requires a correctly configured `profiles.yml` (following dbt's format) with a profile specifically named `elementary` to connect to your data warehouse. Misconfiguration of this profile is a common cause of connection issues.fixEnsure your `~/.dbt/profiles.yml` file contains a profile named `elementary` with valid credentials and connection details for your data warehouse. Refer to Elementary's documentation for required permissions and specific database configurations.
affects: All versions
gotchaPrior to v0.19.4, `float("inf")` (infinity) and `float("nan")` (not a number) values in your data could cause JSON serialization failures when `elementary-data` attempted to generate reports, leading to corrupted or ungeneratable output.fixUpgrade `elementary-data` to version 0.19.4 or later to resolve the JSON serialization issue for `inf` and `nan` float values.
affects: <0.19.4
gotchaThe `elementary_sdk` Python package (distinct from `elementary-data` CLI) is primarily for programmatically sending data quality information to Elementary Cloud and testing Python pipelines. It's not intended for generating the self-hosted reports that the `edr` CLI provides. Confusing their purposes or expecting CLI features from the SDK (or vice-versa) can lead to integration challenges.fixUnderstand the distinct roles: `elementary-data` (CLI, `edr`) for dbt-native report generation and alerts from your data warehouse, and `elementary_sdk` (Python API) for integrating Python-based data quality checks with Elementary Cloud. Use the appropriate tool for your specific need.
affects: All versions
Errors
Common errors & fixes
I run `edr report` and get an empty report.
This is a general symptom indicating that the Elementary dbt package is not correctly deployed, missing metadata, or the CLI tool cannot access the collected data. Common reasons include the dbt package not being up-to-date, `dbt run --select elementary` or `dbt test` not being executed, or an incorrect dbt `materialization` configuration overriding Elementary's settings.
fixEnsure the latest Elementary dbt package version is installed (`dbt deps`), run `dbt run --select elementary` to create necessary tables, and then run `dbt test` to populate them. Verify the `elementary_test_results` table in your data warehouse contains data. Check your `dbt_project.yml` for any `materialization` configurations that might override Elementary's default to tables, and remove them if they conflict. Also, confirm the Elementary CLI is the latest version (`pip install elementary-data --upgrade`).
command not found: edr
The `edr` executable, installed as part of the `elementary-data` Python package, is not located in a directory listed in your system's PATH environment variable, which is common on macOS when Python packages are installed globally.
fixAdd the Python site-packages `bin` directory (e.g., `/Users/user/Library/Python/3.8/bin` or similar, depending on your Python version and installation) to your system's PATH. This typically involves modifying your shell's configuration file (e.g., `.bashrc`, `.zshrc`).
Error: `cannot insert into a view`
This error occurs because some Elementary dbt package models require `INSERT` commands to populate data, but they have been materialized as views instead of tables. This usually happens when there's an overriding `materialization` configuration in your `dbt_project.yml` file that applies broadly to packages.
fixReview your `dbt_project.yml` to ensure the `materialization` configuration is scoped specifically to your own project's models and does not inadvertently override the materialization for dbt packages. If an override exists, adjust it to apply only to your project's models or explicitly configure Elementary's models to be materialized as tables. Afterwards, run `dbt run --select elementary --full-refresh` to recreate the tables correctly.
ModuleNotFoundError: No module named 'pkg_resources'
This `ModuleNotFoundError` typically arises when a package dependency, such as `pyfiglet` (used by `elementary-data`), implicitly relies on `pkg_resources` from `setuptools`, which may be missing or cause issues with newer Python versions (e.g., Python 3.12).
fixEnsure `setuptools` is installed and up-to-date in your environment by running `pip install --upgrade setuptools`. If the issue persists, consider upgrading `pyfiglet` itself to a version compatible with your Python interpreter, or recreate your virtual environment to ensure all dependencies are correctly installed.
Runtime Error Compilation Error in operation elementary-on-run-end-0 (...) 'None' has no attribute 'values'
This dbt compilation error, often seen after upgrading the `elementary-data` dbt package, indicates an issue within Elementary's `on_run_end` dbt hook. It usually means a dictionary or variable expected to hold values is `None` when a macro attempts to access its attributes, like `values`. This can happen if internal metadata tables aren't properly initialized or updated post-upgrade.
fixAfter upgrading the `elementary-data` dbt package, run `dbt run --select elementary` to ensure all necessary Elementary metadata tables and internal structures are correctly created or updated. This step is crucial for the package's macros to function as expected.
Upgrade
Version history
0.23.1latest on PyPI · released Mar 19, 2026
Audit
Dependencies
dbt-corerequiredElementary Data works by integrating with dbt projects and reading dbt artifacts and test results. It requires a dbt package (`elementary-data/elementary`) to be installed in your dbt project.
pydanticrequiredUsed for data validation and schema definition within the library. Compatibility issues have occurred in the past, particularly around major version transitions.