Tablint

Overview

Tablint is a dataset profiler and debugger for machine learning. Think of it as “Pandas Profiling + a linter for datasets” that runs before you train.

It scans your data, surfaces critical issues, explains why they matter for modeling, and suggests (or generates) concrete fixes. You can use it as a single CLI command or as a Python library inside your pipelines.

Installation

Using pip

pip install tablint

Using uv (recommended)

# Install uv (if needed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Tablint
uv pip install tablint

# Or from source
git clone https://github.com/cachevector/tablint.git
cd tablint
uv sync

After installation, the tablint command is available directly in your terminal.

Quickstart — CLI

1. Run a quick scan

Get a concise summary of dataset issues in your terminal.

tablint scan dataset.csv

Common options

--target COLUMN — target column for ML-specific checks
--checks outliers,high_missing_values — run only selected checks
--json — JSON output for automation
--sample-size N — restrict analysis to N rows

Example

tablint scan train.csv \
  --target Survived \
  --checks outliers,high_missing_values,class_imbalance

2. Detailed analysis

Drill into every issue Tablint found.

tablint details train.csv --target Survived

Quickstart — Python

Basic analysis

import pandas as pd
from tablint import DatasetAnalyzer

df = pd.read_csv("dataset.csv")

analyzer = DatasetAnalyzer(df)
summary = analyzer.analyze()

print("Critical issues:", summary["critical_count"])
print("Warnings:", summary["warning_count"])

With a target column

analyzer = DatasetAnalyzer(
    df,
    target_col="target",
)
summary = analyzer.analyze()

Run specific checks

analyzer = DatasetAnalyzer(
    df,
    selected_checks=["outliers", "high_missing_values", "class_imbalance"],
)
summary = analyzer.analyze()

Reports

Generate a report from the CLI

tablint report dataset.csv --format html --theme minimal

Reports can be exported as md, json, html, or pdf, using the --format flag. Use --with-code to generate companion Python scripts with cleaning logic and pipelines.

Generate reports from Python

from tablint import DatasetAnalyzer
from tablint.reports import generate_report

analyzer = DatasetAnalyzer(df, include_plots=True)
summary = analyzer.analyze()

generate_report(
    summary,
    format="html",
    full=True,
    output_file="dataset_tablint_report.html",
    theme="minimal",
)

CLI reference

`tablint scan`

Run a quick scan and print a compact summary of issues to the terminal. Ideal for a fast health check during development.

tablint scan dataset.csv --target Survived

--target COLUMN — target column for ML checks (class imbalance, leakage, etc.)
--checks LIST — comma-separated list of checks to run
--comparison FILE — compare with another dataset for drift detection
--critical-only — hide warnings and show only critical issues
--json — emit JSON instead of human-readable text
--quiet — minimal output, useful in CI
--sample-size N / --no-sample — control automatic sampling
--config FILE — load thresholds from a YAML, TOML, or JSON file

`tablint details`

Produce a verbose, line-by-line description of each issue in the dataset, with statistics and recommendations.

tablint details dataset.csv --target Survived

Accepts the same options as scan (including --comparison and --config) and is best used when you are actively debugging a dataset or deciding which columns to drop or transform.

`tablint report`

Generate a full report in HTML, PDF, Markdown, or JSON. Reports contain summaries, plots, and (optionally) auto-generated Python code.

tablint report dataset.csv --format html --theme minimal --with-code

--format {md,json,html,pdf} — output format (Markdown is the default)
--theme {minimal,neubrutalism} — HTML theme
--with-code — write companion _fixes.py and _pipeline.py files
--comparison FILE — compare two datasets for drift (train vs test, etc.)
--sample-size N / --no-sample — control automatic sampling
--config FILE — load thresholds from a YAML, TOML, or JSON file

Exit codes

Tablint is CI-friendly: non-zero exit codes indicate that critical issues were detected or an internal error occurred. You can wire this into pre-commit hooks or data-quality checks in your pipeline.

Python API

`DatasetAnalyzer`

The core entry point for programmatic usage. It accepts a pandas DataFrame and optional configuration for targets, sampling, comparison datasets, and which checks to run.

from tablint import DatasetAnalyzer

analyzer = DatasetAnalyzer(
    df,
    target_col="target",
    selected_checks=["outliers", "high_missing_values"],
    include_plots=True,
)
summary = analyzer.analyze()

The returned summary is a JSON-serializable dictionary with keys such as:

critical_count / warning_count
issues — list of individual issues with severity, column, check name, and message
summaries — per-column statistics and optional plots
sampling_info — information about any sampling that was applied

Sampling large datasets

For very large tables, you can control how many rows Tablint inspects using a sampling configuration. This keeps runtimes predictable in production.

from tablint.utils.sampling import SamplingConfig

sampling = SamplingConfig(max_rows=10000)

analyzer = DatasetAnalyzer(
    df,
    sampling_config=sampling,
    auto_sample=True,
)
summary = analyzer.analyze()

When sampling is applied, summary["sampling_info"] contains details such as fractions and original row counts.

Generating fix scripts and pipelines

Beyond reports, Tablint can emit executable Python code that encodes suggested fixes and ML pipelines.

from tablint.checks.core import Issue
from tablint.preparers.codegen import CodeGenerator
from tablint.preparers.pipeline_builder import PipelineBuilder
from tablint.preparers.suggestions import SuggestionProvider

issues = [Issue(**i) for i in summary["issues"]]
column_types = summary.get("column_types", dict())

provider = SuggestionProvider(
    issues=issues,
    column_types=column_types,
    target_col="target",
)
suggestions = provider.get_suggestions()

codegen = CodeGenerator(suggestions)
fixes_code = codegen.generate_pandas_script()

builder = PipelineBuilder(suggestions)
pipeline_code = builder.generate_pipeline_code()

You can write these strings to disk (for example, fixes.py and pipeline.py) or load them dynamically in your tooling.

Drift detection

To compare training and serving data, construct a DatasetAnalyzer with both a primary and comparison dataset and enable the dataset_drift check.

analyzer = DatasetAnalyzer(
    train_df,
    comparison_df=test_df,
    selected_checks=["dataset_drift"],
)
summary = analyzer.analyze()

Available checks

Data quality

dataset_missingness — overall missing data patterns
high_missing_values — columns with heavy missingness
missing_patterns — correlated missing value patterns
duplicates — duplicate rows
empty_columns — completely empty columns
empty_dataset — empty or all-missing datasets
single_value_columns — near-constant features
mixed_data_types — columns with mixed data types

Distribution & statistics

outliers — z-score outlier detection
skewness — highly skewed numeric distributions
high_cardinality — too many unique categorical values
uniform_distribution — uniformly distributed numeric columns
unique_values — columns where >95% values are unique
high_zero_counts — features dominated by zeros
infinite_values — columns containing infinite values
constant_length — string columns with constant character length
extreme_text_lengths — text columns with extreme value lengths
normality — non-normal distributions (Shapiro-Wilk / D’Agostino-Pearson)
variance_homogeneity — unequal variances across target groups (Levene’s test)

ML-specific

class_imbalance — target imbalance (requires --target)
feature_correlation — highly correlated numeric features
categorical_correlation — highly associated categorical features
mixed_correlation — numeric-categorical associations
data_leakage — columns identical to target
target_leakage_patterns — features leaking target information
low_mutual_information — near-zero MI with target (requires --target)
dataset_drift — drift between train / test datasets (requires --comparison)
datetime_skew — datetime columns concentrated in one period
datetime_future_dates — datetime values in the future
datetime_gaps — anomalous gaps in datetime sequences
datetime_monotonicity — non-monotonic datetime columns

Configuration

Every detection threshold in Tablint has a sensible default. You can override any of them at runtime by providing a config file — no code changes required.

Supported formats

Config files can be written in YAML (.yaml / .yml), TOML (.toml), or JSON (.json). Only the keys you specify are changed; everything else falls back to defaults.

# tablint.yaml
missing_values:
  warning: 0.3
  critical: 0.6
outliers:
  z_score: 3.5
statistical_tests:
  normality_p_value: 0.01
mutual_info:
  low_mi_warning: 0.05

Via CLI

tablint scan dataset.csv \
  --config tablint.yaml

tablint report dataset.csv \
  --format html \
  --config tablint.toml

Via Python

from tablint.utils.config_loader import load_config
from tablint import DatasetAnalyzer

config = load_config("tablint.yaml")
analyzer = DatasetAnalyzer(df, config=config)
summary = analyzer.analyze()

Contributing

Tablint is open source and welcomes contributions. If you want to fix a bug, add a check, or improve the reports:

Read the contribution guide
Open an issue describing the change you’d like to make
Create a pull request with clear motivation and tests where appropriate

Learn Tablint in minutes, not hours.