666ghj/MiroFish · error · ImportError

需要安装PyMuPDF: pip install PyMuPDF

Error message

需要安装PyMuPDF: pip install PyMuPDF

What it means

ImportError raised inside _extract_from_pdf when 'import fitz' (PyMuPDF) fails because the package is not installed in the current environment. PDF extraction is optional functionality whose dependency is only imported on demand, so the error appears exactly when the first PDF is parsed.

Source

Thrown at backend/app/utils/file_parser.py:116

        if suffix not in cls.SUPPORTED_EXTENSIONS:
            raise ValueError(f"不支持的文件格式: {suffix}")
        
        if suffix == '.pdf':
            return cls._extract_from_pdf(file_path)
        elif suffix in {'.md', '.markdown'}:
            return cls._extract_from_md(file_path)
        elif suffix == '.txt':
            return cls._extract_from_txt(file_path)
        
        raise ValueError(f"无法处理的文件格式: {suffix}")
    
    @staticmethod
    def _extract_from_pdf(file_path: str) -> str:
        """从PDF提取文本"""
        try:
            import fitz  # PyMuPDF
        except ImportError:
            raise ImportError("需要安装PyMuPDF: pip install PyMuPDF")
        
        text_parts = []
        with fitz.open(file_path) as doc:
            for page in doc:
                text = page.get_text()
                if text.strip():
                    text_parts.append(text)
        
        return "\n\n".join(text_parts)
    
    @staticmethod
    def _extract_from_md(file_path: str) -> str:
        """从Markdown提取文本，支持自动编码检测"""
        return _read_text_with_fallback(file_path)
    
    @staticmethod
    def _extract_from_txt(file_path: str) -> str:
        """从TXT提取文本，支持自动编码检测"""

View on GitHub (pinned to b5b53acc57)

Solutions

1. Install PyMuPDF: pip install PyMuPDF (as the message says)
2. Add PyMuPDF to the project's locked dependencies if PDF support is required
3. Alternatively, pre-check importability and return a clear feature-unavailable response to the caller instead of failing mid-parse

Example fix

# before
# PyMuPDF missing from requirements.txt; first PDF upload crashes with ImportError

# after
# requirements.txt
PyMuPDF==1.24.*

try:
    import fitz  # noqa: F401
    PDF_OK = True
except ImportError:
    PDF_OK = False

if path.suffix == '.pdf' and not PDF_OK:
    return http_error(501, "PDF extraction unavailable: PyMuPDF not installed")

try:
    text = FileParser.extract_text(pdf_path)
except ImportError as e:
    logger.error("dependency missing: %s", e)
    raise

When it happens

Trigger: Calling extract_text on a .pdf file in an environment where PyMuPDF is not installed — typically because it was left out of requirements.txt/pyproject or the deployment image, while the developer machine had it.

Common situations: Dependency declared as optional or forgotten in deployment (Docker image, CI), different virtual environments between dev and prod, or a fresh clone without the extra dependency installed.

Related errors

• GitHub CLI (gh) is required for backfill

AI-assisted analysis of 666ghj/MiroFish@b5b53acc57 (2026-08-14). Data as JSON: /api/errors/406b847593c2be1b. Report an issue: GitHub.