Format Support¶

Kreuzberg supports 56 file formats across major categories, providing comprehensive document intelligence capabilities through native Rust extractors and LibreOffice conversion.

Overview¶

Kreuzberg v4 uses a high-performance Rust core with two extraction methods:

• Native Rust Extractors: Fast, memory-efficient extractors for common formats
• LibreOffice Conversion: Legacy Microsoft Office format support (.doc, .ppt)

All formats support async/await and batch processing. Image formats and PDFs support optional OCR when configured.

Format Support Matrix¶

Office Documents¶

Text & Markup¶

Structured Data¶

Email¶

Images¶

All image formats support OCR when configured with ocr parameter in ExtractionConfig.

Archives¶

Academic & Publishing (Native)¶

Markdown Variants (Native)¶

Other Formats¶

Architecture Diagram¶

graph TD
    A[File Input] --> B{MIME Detection}
    B --> C{Extraction Method}

    C -->|Native Format| D[Rust Core Extractors]
    C -->|Legacy Office| F[LibreOffice Conversion]

    D --> G[PDF Extractor]
    D --> H[Excel Extractor]
    D --> I[Image Extractor]
    D --> J[XML/Text/HTML Extractors]
    D --> K[Email Extractor]
    D --> L[Archive Extractor]

    F --> N[Convert DOC→DOCX]
    F --> O[Convert PPT→PPTX]
    N --> D
    O --> D

    G --> P{OCR Needed?}
    I --> P
    P -->|Yes| Q[Tesseract OCR]
    P -->|No| R[Text Output]
    Q --> R

    H --> R
    J --> R
    K --> R
    L --> R

    R --> S[Post-Processing Pipeline]
    S --> T[Final Result]

Feature Flags¶

Kreuzberg uses Cargo feature flags to enable optional format support:

Note: No features are enabled by default (default = []). You must explicitly enable the features you need.

To enable specific features:

[dependencies]
# Enable only PDF and Excel format support
kreuzberg = { version = "4.0", features = ["pdf", "excel"] }

To enable all features with --all-features:

# Build with all format extraction features enabled
cargo build --all-features

Or use the convenience bundles:

[dependencies]
# All format extraction features (no server components)
kreuzberg = { version = "4.0", features = ["full"] }

# Server features (API, MCP) with common format support
kreuzberg = { version = "4.0", features = ["server"] }

# CLI features with commonly used formats
kreuzberg = { version = "4.0", features = ["cli"] }

System Dependencies¶

Some formats require external system tools:

Tesseract OCR (Optional)¶

Required for OCR on images and PDFs:

# Install Tesseract OCR on macOS
brew install tesseract

# Install Tesseract OCR on Ubuntu/Debian
sudo apt-get install tesseract-ocr

# Install Tesseract OCR on RHEL/CentOS/Fedora
sudo dnf install tesseract

# Install Tesseract OCR on Windows (using Scoop)
scoop install tesseract

LibreOffice (Optional)¶

Required for legacy Microsoft Office formats (.doc, .ppt):

# Install LibreOffice on macOS
brew install libreoffice

# Install LibreOffice on Ubuntu/Debian
sudo apt-get install libreoffice

# Install LibreOffice on RHEL/CentOS/Fedora
sudo dnf install libreoffice

# Windows: Download from https://www.libreoffice.org/download/

Docker Note: All system dependencies are pre-installed in official Kreuzberg Docker images.

Format Detection¶

Kreuzberg automatically detects file formats using:

1. File Extension Mapping: 56 formats mapped to MIME types
2. mime_guess Crate: Fallback for unknown extensions
3. Manual Override: Explicit MIME type can be provided

Example with manual override:

using Kreuzberg;

// Automatic format detection from file extension
var result = KreuzbergClient.ExtractFileSync("document.pdf");

// Manual MIME type override for files without extensions
var result2 = KreuzbergClient.ExtractFileAsBytes(rawBytes, "application/pdf", null);

import "kreuzberg"

// Automatic format detection from file extension
result, err := kreuzberg.ExtractFileSync("document.pdf", nil)
if err != nil {
    log.Fatal(err)
}

// Manual MIME type override for ambiguous files
config := &kreuzberg.ExtractionConfig{}
mimeBytes, _ := ioutil.ReadFile("document.dat")
result2, err := kreuzberg.ExtractBytesSync(mimeBytes, "application/pdf", config)

import dev.kreuzberg.Kreuzberg;
import dev.kreuzberg.ExtractionResult;

// Automatic format detection from file extension
ExtractionResult result = Kreuzberg.extractFile("document.pdf");

// Manual MIME type override using detectMimeType for byte arrays
String mimeType = Kreuzberg.detectMimeType(new byte[]{/* PDF header bytes */});
ExtractionResult result2 = Kreuzberg.extractFileAsBytes(rawBytes, mimeType, null);

from kreuzberg import extract_file

# Automatic format detection from file extension
result = extract_file("document.pdf")

# Manual MIME type override for unknown extensions
result = extract_file("document.dat", mime_type="application/pdf")

require 'kreuzberg'

# Automatic format detection from file extension
result = Kreuzberg.extract_file_sync('document.pdf')

# Manual MIME type override for files with ambiguous extensions
config = Kreuzberg::Config::Extraction.new
result = Kreuzberg.extract_file_sync('document.dat', mime_type: 'application/pdf', config: config)

use kreuzberg::{extract_file, ExtractionConfig};

#[tokio::main]
async fn main() -> kreuzberg::Result<()> {
    let config = ExtractionConfig::default();

    // Automatic format detection from file extension
    let result = extract_file("document.pdf", None, &config).await?;

    // Manual MIME type override for extensionless files
    let result = extract_file("document.dat", Some("application/pdf"), &config).await?;

    Ok(())
}

import { extractFile } from '@kreuzberg/node';

// Automatic format detection from file extension
const result = await extractFile('document.pdf');

// Manual MIME type override for files with no extension
const result2 = await extractFile('document.dat', { mimeType: 'application/pdf' });

OCR Support¶

OCR is available for:

• All image formats (PNG, JPEG, WebP, BMP, TIFF, GIF, etc.)
• PDF documents (with automatic fallback for scanned PDFs)
• Embedded images in PowerPoint presentations

Configuration¶

from kreuzberg import extract_file, ExtractionConfig, OcrConfig, TesseractConfig

# Configure OCR with multi-language support and custom Tesseract settings
config = ExtractionConfig(
    ocr=OcrConfig(
        tesseract_config=TesseractConfig(
            lang="eng+deu",  # Multiple languages: English and German
            psm=3,           # Page segmentation mode: Auto
            oem=1            # OCR Engine mode: LSTM neural net
        )
    ),
    force_ocr=False  # Only use OCR when native text extraction is insufficient
)

result = extract_file("scanned_document.pdf", config=config)

Automatic OCR Decision¶

For PDFs, Kreuzberg automatically decides whether OCR is needed by analyzing native text:

• No OCR: Document has substantial, meaningful text (>64 non-whitespace chars, >32 chars/page average)
• OCR Fallback: Document appears scanned (mostly punctuation, very low alphanumeric ratio)

Override with force_ocr=True to always use OCR regardless of native text quality.

Performance Characteristics¶

Native Rust Extractors¶

• PDF: Significantly faster than Python libraries due to native Rust implementation
• Excel: Streaming parser, handles multi-GB files
• XML: Streaming parser, memory-efficient for large documents
• Text/Markdown: Streaming parser with lazy regex compilation
• Archives: Efficient extraction without full decompression

LibreOffice Extractors¶

• Higher overhead (~500-2000ms per file)
• Only used for legacy formats (.doc, .ppt)
• Automatic conversion to modern formats

Batch Processing¶

All formats support concurrent batch processing:

from kreuzberg import batch_extract_file, ExtractionConfig

# Process multiple files concurrently for better throughput
paths = ["file1.pdf", "file2.docx", "file3.xlsx"]
config = ExtractionConfig(max_concurrent_extractions=8)

results = batch_extract_file(paths, config=config)

Format Limitations¶

Known Limitations¶

• Password-Protected PDFs: Requires crypto extra (pip install kreuzberg[crypto])
• Legacy Excel (.xls): Formula evaluation not supported (values only)
• Encrypted Office Documents: Password protection not supported
• Multi-page TIFF: OCR processes first page only (configurable)
• Animated GIF: Extracts first frame only

Unsupported Formats¶

• Video formats (MP4, AVI, MOV, etc.)
• Audio formats (MP3, WAV, FLAC, etc.)
• CAD formats (DWG, DXF, etc.)
• Database files (MDB, ACCDB, etc.)
• Compressed Office formats without proper headers

Adding New Formats¶

Kreuzberg's plugin system allows adding custom format extractors:

using Kreuzberg;
using Kreuzberg.Plugins;

// Custom document extractor for proprietary format support
public class CustomExtractor : IDocumentExtractor
{
    public string Name => "custom-format-extractor";

    public string[] SupportedMimeTypes => new[] { "application/x-custom" };

    public ExtractionResult ExtractBytes(byte[] content, string mimeType, ExtractionConfig config)
    {
        // Implement custom extraction logic for your format
        var text = ParseCustomFormat(content);
        return new ExtractionResult
        {
            Content = text,
            MimeType = mimeType,
            Metadata = new Dictionary<string, object>()
        };
    }
}

// Register the custom extractor with Kreuzberg
KreuzbergClient.RegisterDocumentExtractor(new CustomExtractor());

package main

import (
    "kreuzberg"
    "log"
)

// CustomExtractor implements DocumentExtractor for proprietary formats
type CustomExtractor struct{}

func (e *CustomExtractor) Name() string {
    return "custom-format-extractor"
}

func (e *CustomExtractor) SupportedMimeTypes() []string {
    return []string{"application/x-custom"}
}

func (e *CustomExtractor) ExtractBytes(content []byte, mimeType string, config *kreuzberg.ExtractionConfig) (*kreuzberg.ExtractionResult, error) {
    // Implement custom parsing logic for your file format
    text := parseCustomFormat(content)
    return &kreuzberg.ExtractionResult{
        Content:  text,
        MimeType: mimeType,
        Success:  true,
    }, nil
}

// Register the custom extractor during package initialization
func init() {
    if err := kreuzberg.RegisterDocumentExtractor("custom-format-extractor", &CustomExtractor{}); err != nil {
        log.Fatal(err)
    }
}

import dev.kreuzberg.Kreuzberg;
import dev.kreuzberg.DocumentExtractorProtocol;
import dev.kreuzberg.ExtractionResult;
import dev.kreuzberg.config.ExtractionConfig;

// Custom document extractor for unsupported file formats
public class CustomExtractor implements DocumentExtractorProtocol {
    @Override
    public String name() {
        return "custom-format-extractor";
    }

    @Override
    public String[] supportedMimeTypes() {
        return new String[]{"application/x-custom"};
    }

    @Override
    public ExtractionResult extractBytes(
        byte[] content,
        String mimeType,
        ExtractionConfig config) throws Exception {
        // Implement format-specific extraction logic
        String text = parseCustomFormat(content);
        return new ExtractionResult(text, mimeType, true, null);
    }
}

// Register the custom extractor
Kreuzberg.registerDocumentExtractor(new CustomExtractor());

from kreuzberg import DocumentExtractor, ExtractionResult, Metadata

# Custom extractor for proprietary or unsupported file formats
class CustomExtractor(DocumentExtractor):
    def name(self) -> str:
        return "custom-format-extractor"

    def supported_mime_types(self) -> list[str]:
        return ["application/x-custom"]

    def extract_bytes(self, content: bytes, mime_type: str, config) -> ExtractionResult:
        # Implement parsing logic specific to your format
        text = parse_custom_format(content)
        return ExtractionResult(
            content=text,
            mime_type=mime_type,
            metadata=Metadata()
        )

# Register the custom extractor with Kreuzberg's registry
from kreuzberg import get_document_extractor_registry
registry = get_document_extractor_registry()
registry.register(CustomExtractor())

require 'kreuzberg'

# Custom document extractor for new file format support
class CustomExtractor
  def name
    'custom-format-extractor'
  end

  def supported_mime_types
    ['application/x-custom']
  end

  def extract_bytes(content, mime_type, config)
    # Implement your custom format parsing logic
    text = parse_custom_format(content)
    Kreuzberg::Result.new(
      content: text,
      mime_type: mime_type,
      metadata: {}
    )
  end
end

# Register the custom extractor
Kreuzberg.register_document_extractor(CustomExtractor.new)

use kreuzberg::plugins::{DocumentExtractor, Plugin};
use kreuzberg::types::ExtractionResult;
use async_trait::async_trait;

// Custom document extractor for proprietary file formats
pub struct CustomExtractor;

impl Plugin for CustomExtractor {
    fn name(&self) -> &str {
        "custom-format-extractor"
    }

    fn version(&self) -> String {
        "1.0.0".to_string()
    }
}

#[async_trait]
impl DocumentExtractor for CustomExtractor {
    async fn extract_bytes(
        &self,
        content: &[u8],
        mime_type: &str,
        config: &ExtractionConfig,
    ) -> kreuzberg::Result<ExtractionResult> {
        // Implement format-specific parsing logic
        let text = parse_custom_format(content)?;
        Ok(ExtractionResult {
            content: text,
            mime_type: mime_type.to_string(),
            ..Default::default()
        })
    }

    fn supported_mime_types(&self) -> &[&str] {
        &["application/x-custom"]
    }
}

// Register the custom extractor with Kreuzberg's plugin registry
use kreuzberg::plugins::registry::get_document_extractor_registry;
use std::sync::Arc;

let registry = get_document_extractor_registry();
registry.write().unwrap().register(Arc::new(CustomExtractor))?;

import { registerDocumentExtractor, type DocumentExtractorProtocol } from '@kreuzberg/node';

// Custom document extractor for new or proprietary file formats
class CustomExtractor implements DocumentExtractorProtocol {
    name(): string {
        return "custom-format-extractor";
    }

    supportedMimeTypes(): string[] {
        return ["application/x-custom"];
    }

    async extractBytes(content: Uint8Array, mimeType: string, config?: ExtractionConfig): Promise<ExtractionResult> {
        // Implement custom parsing logic for your format
        const text = parseCustomFormat(content);
        return {
            content: text,
            mimeType: mimeType,
            success: true,
            metadata: {}
        };
    }
}

// Register the custom extractor
registerDocumentExtractor(new CustomExtractor());

See Also¶

• Configuration Reference - Detailed configuration options
• Extraction Guide - Extraction examples
• OCR Guide - OCR configuration and usage
• Plugin System - Custom extractor development