NanmiCoder/MediaCrawler · error · ImportError

openpyxl is required for Excel export. Install it with: pip

Error message

openpyxl is required for Excel export. Install it with: pip install openpyxl

What it means

Raised by ExcelStoreBase.__init__ when the openpyxl package is absent (EXCEL_AVAILABLE is False). Excel is treated as an optional dependency — importing store modules works, but instantiating any platform's excel store (SAVE_DATA_OPTION='excel') raises ImportError with install instructions.

Source

Thrown at store/excel_store_base.py:105

        with cls._lock:
            for key, instance in cls._instances.items():
                try:
                    instance.flush()
                    utils.logger.info(f"[ExcelStoreBase] Flushed instance: {key}")
                except Exception as e:
                    utils.logger.error(f"[ExcelStoreBase] Error flushing {key}: {e}")
            cls._instances.clear()

    def __init__(self, platform: str, crawler_type: str = "search"):
        """
        Initialize Excel store

        Args:
            platform: Platform name (xhs, dy, ks, etc.)
            crawler_type: Type of crawler (search, detail, creator)
        """
        if not EXCEL_AVAILABLE:
            raise ImportError(
                "openpyxl is required for Excel export. "
                "Install it with: pip install openpyxl"
            )

        super().__init__()
        self.platform = platform
        self.crawler_type = crawler_type

        # Create data directory
        if config.SAVE_DATA_PATH:
            self.data_dir = Path(config.SAVE_DATA_PATH) / platform
        else:
            self.data_dir = Path("data") / platform
        self.data_dir.mkdir(parents=True, exist_ok=True)

        # Initialize workbook
        self.workbook = openpyxl.Workbook()
        self.workbook.remove(self.workbook.active)  # Remove default sheet

View on GitHub (pinned to d6f7c5bb90)

Solutions

pip install openpyxl (or add it to your requirements/lockfile)
If using the project's extras mechanism, install with the excel extra, e.g. pip install '.[excel]' where provided
In Docker/CI, add openpyxl to the image dependencies
Alternatively switch SAVE_DATA_OPTION to csv/json/sqlite which need no extra packages

Example fix

# before
SAVE_DATA_OPTION = "excel"   # ImportError: openpyxl is required

# after
pip install openpyxl
SAVE_DATA_OPTION = "excel"   # now works

Defensive patterns

Strategy: validation

Validate before calling

def excel_export_ready() -> bool:
    try:
        import openpyxl  # noqa: F401
        return True
    except ImportError:
        return False

if config.SAVE_DATA_OPTION == "excel" and not excel_export_ready():
    raise SystemExit("install openpyxl first: pip install openpyxl")

Type guard

def can_use_excel_store() -> bool:
    import importlib.util
    return importlib.util.find_spec("openpyxl") is not None

Try / catch

try:
    store = XhsExcelStoreImplement()
except ImportError as e:
    raise SystemExit(f"missing optional dependency: {e}. Run: pip install openpyxl") from e

Prevention

Add openpyxl to requirements/Docker image when SAVE_DATA_OPTION is 'excel'
Feature-check optional deps at startup and fail with an install hint
Fall back to csv export if Excel is not installable in the environment

When it happens

Trigger: Running any crawler with SAVE_DATA_OPTION='excel' in an environment where 'pip install openpyxl' was never executed — including fresh clones, slim Docker images, and CI runners that only install base requirements.

Common situations: New deployment without the excel extra; a Dockerfile that skips optional deps; switching SAVE_DATA_OPTION to 'excel' on an existing install that never needed it before.

Related errors

AI-assisted analysis of NanmiCoder/MediaCrawler@d6f7c5bb90 (2026-08-15). Data as JSON: /api/errors/daa460ed9e5e3def. Report an issue: GitHub.