Stirling-Tools/Stirling-PDF · error · ImportError

The 'tomlkit' library is not installed. Please install it us

Error message

The 'tomlkit' library is not installed. Please install it using 'pip install tomlkit'.

What it means

ImportError raised at module load time because the tomlkit third-party library is not installed. The script imports tomlkit to read/write TOML translation files; without the dependency it cannot run.

Source

Thrown at scripts/counter_translation_v3.py:59

Arguments:
    -l, --lang <locale or file> Specific locale to check (e.g. 'de-DE'),
                                a directory, or a full path to translation.toml.
    --show-percentage           Print only the percentage (no formatting, ideal for CI/CD).
    --show-missing-keys         Show the list of missing keys when checking a single language file.
"""

import argparse
import glob
import os
import re
import sys
from collections.abc import Iterable, Mapping

# Ensure tomlkit is installed before importing
try:
    import tomlkit
except ImportError:
    raise ImportError("The 'tomlkit' library is not installed. Please install it using 'pip install tomlkit'.")

sys.stdout.reconfigure(encoding="utf-8", errors="replace")


def convert_to_multiline(data: tomlkit.TOMLDocument) -> tomlkit.TOMLDocument:
    """Converts 'ignore' and 'missing' arrays to multiline arrays and sorts the first-level keys of the TOML document.

    Enhances readability and consistency in the TOML file by ensuring arrays contain unique and sorted entries.

    Args:
        data (tomlkit.TOMLDocument): The original TOML document containing the data.

    Returns:
        tomlkit.TOMLDocument: A new TOML document with sorted keys and properly formatted arrays.
    """
    sorted_data = tomlkit.document()
    for key in sorted(data.keys()):
        value = data[key]

View on GitHub (pinned to 9ef20dcab8)

Solutions

1. Install the dependency: pip install tomlkit.
2. Install all script deps if a requirements file exists: pip install -r scripts/requirements.txt.
3. Pin tomlkit in the project's dependency manifest so it is installed alongside dev tools.

Example fix

# before: ImportError on import
# after
pip install tomlkit
# then re-run: python scripts/counter_translation_v3.py ...

# Pre-flight check before running the script
python -c "import tomlkit" 2>/dev/null || pip install tomlkit

When it happens

Trigger: Running scripts/counter_translation_v3.py in an environment where tomlkit is not installed (no pip install, not in the active virtualenv).

Common situations: Fresh checkout without installing script dependencies. Wrong/activating a different virtualenv. Running in CI without the scripts requirements installed.

Related errors

• Command {' '.join(cmd)} failed: {result.stderr}
• File not found: {json_path}
• Unexpected JSON structure (expected an object at root).
• Failed to parse {path}: {exc}
• No URLs supplied. Use --urls and/or --urls-file.

AI-assisted analysis of Stirling-Tools/Stirling-PDF@9ef20dcab8 (2026-08-13). Data as JSON: /api/errors/3fe353affa267dac. Report an issue: GitHub.