opengraph-linter

A pluggable CLI meta-tag inspector for Open Graph and X card tags — a terminal take on opengraph.xyz.

Install

uv tool install opengraph-linter             # core: reports without previews
uv tool install "opengraph-linter[preview]"  # + inline og:image previews

The inline preview needs the optional preview extra (textual-image), and is off by default. Turn it on with --preview or with preview = true in the config. Without the extra, the report still runs every rule and prints a one-line hint instead of the picture.

Usage

# straight from a checkout, no install
uv run src/opengraph_linter https://example.com/

# the installed console script; several URLs work in one run
uv run opengraph-linter https://example.com/ https://example.org/

# equivalents
uv run python -m opengraph_linter https://example.com/
uv run scripts/og_preview.py https://example.com/

Options:

Exit codes: 0 clean, 1 critical findings (warnings too with --strict), 2 a page could not be fetched or an option was invalid. A run with several URLs prints one panel per URL and a final overview table.

--json emits a list with one {url, findings} object per URL.

Configuration

Every threshold lives on the Settings model. Override any field from a [tool.opengraph-linter] table in the pyproject.toml of the directory you run from:

[tool.opengraph-linter]
og_title_max = 70
max_image_bytes = 8388608
# render og:image inline (needs the `preview` extra, off by default);
# --preview/--no-preview wins
preview = true
# rules to skip on every run, by lint code or rule id
ignore = ["OG004", "image-conversion-text"]

When pyproject.toml has no [tool.opengraph-linter] table, the linter falls back on an opengraph-linter.toml file in the same directory. Its keys sit at the top level:

# opengraph-linter.toml
og_title_max = 70
ignore = ["OG004", "image-conversion-text"]

The ignore list is merged with any --disable flags. An unknown code or id in either place exits with code 2.

Rules

Every data point is a Rule — a lint code, an id, a tag, and a check(context) -> Finding. Twenty-three ship built in. Each reports critical, warning, or success; the "Fails as" column shows the severity when the check does not pass. Ignore any of them by code or id with --disable or the ignore list.

Open Graph (OG)

X / Twitter cards (TW)

The og:image asset (IMG)

Plain SEO tags (SEO)

The IMG rules that need the downloaded file (IMG002–IMG004) report a warning when the image was not fetched, for example with --skip-image-checks. Run opengraph-linter --list-rules for the same table in the terminal.

The conversion-text rule is a heuristic, not OCR: it measures how much of the image is covered by its dominant flat colors, which separates designed cards from photographs and auto-generated video thumbnails. Every threshold lives on the Settings model in src/opengraph_linter/models.py.

Plugins

Rules are registered through pluggy, so a separate package can add or replace them:

from opengraph_linter import Rule, hookimpl


class FacebookAppId(Rule):
    id = "fb-app-id"
    code = "FB001"  # pick an unused prefix for your plugin
    tag = "fb:app_id"
    description = "fb:app_id is set for Facebook insights"
    order = 35

    def check(self, context):
        value = context.page.get("fb:app_id")
        if not value:
            return self.warn("Facebook app id is missing", "Set fb:app_id.")
        return self.ok("Facebook app id is set", value)


@hookimpl
def opengraph_rules():
    return [FacebookAppId()]

Expose it as an opengraph_linter entry point and it loads automatically:

[project.entry-points.opengraph_linter]
my-rules = "my_package.rules"

Two hooks are available:

• opengraph_rules() — return rules to add. Reusing a built-in id replaces it.
• opengraph_finding(finding, context) — return a Finding to override one, or None to leave it alone.

Rules are plain classes; everything they consume and emit — Page, ImageInfo, Settings, Context, Finding — is a pydantic model.