PDF Report Configuration

Overview

OpenAVM Kit can generate comprehensive PDF reports for your valuation analyses, ratio studies, and equity assessments. This feature uses wkhtmltopdf, a command-line tool that converts HTML to PDF with high-quality rendering.

PDF generation is optional. If you don’t install wkhtmltopdf, you can still generate HTML and Markdown reports. The rest of OpenAVM Kit will work normally.

Why PDF Reports?

PDF reports offer several advantages:

Professional presentation - Share polished reports with stakeholders
Archival format - Long-term storage with consistent rendering
Print-ready - Generate reports suitable for printing
Self-contained - All content embedded in a single file
Universal compatibility - Opens on any device without special software

Prerequisites

OpenAVM Kit uses two components for PDF generation:

pdfkit - Python wrapper (installed automatically with OpenAVM Kit)
wkhtmltopdf - System command-line tool (requires manual installation)

You must install wkhtmltopdf manually on your system. It is not installed by pip and cannot be included in Python packages.

Installation

Windows

Download Installer

Visit the wkhtmltopdf downloads page and download the Windows installer (.exe file).Choose the appropriate version:

64-bit for most modern systems
32-bit for older systems

Run Installer

Run the downloaded installer and follow the installation wizard.Important: Pay attention to the installation directory. Common locations:

C:\Program Files\wkhtmltopdf\
C:\Program Files (x86)\wkhtmltopdf\

Add to PATH

Add the wkhtmltopdf\bin directory to your system PATH:

Open System Properties (Right-click “This PC” → Properties)
Click Advanced system settings
Click Environment Variables
Under “System variables”, find and select Path
Click Edit
Click New
Add the path to the bin folder (e.g., C:\Program Files\wkhtmltopdf\bin)
Click OK on all dialogs

For detailed instructions with screenshots, see this PATH tutorial.

Verify Installation

Open a new Command Prompt and run:

wkhtmltopdf --version

You should see version information like:

wkhtmltopdf 0.12.6

You must open a new Command Prompt after modifying PATH. Existing terminals won’t see the updated PATH.

macOS

Install Homebrew (if needed)

If you don’t have Homebrew installed, get it from brew.sh or run:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install wkhtmltopdf

Use Homebrew to install wkhtmltopdf:

brew install wkhtmltopdf

This will download, compile, and install wkhtmltopdf along with all dependencies.

Verify Installation

Check that wkhtmltopdf is installed:

wkhtmltopdf --version

You should see version information:

wkhtmltopdf 0.12.6

Linux (Debian/Ubuntu)

Update Package List

Update your package manager:

sudo apt-get update

Install wkhtmltopdf

Install wkhtmltopdf and dependencies:

sudo apt-get install wkhtmltopdf

This will install wkhtmltopdf along with required system libraries like X11 for rendering.

Verify Installation

Check the installation:

wkhtmltopdf --version

Expected output:

wkhtmltopdf 0.12.6

Linux (Other Distributions)

Red Hat/CentOS/Fedora

sudo yum install wkhtmltopdf
# or for newer systems
sudo dnf install wkhtmltopdf

Arch Linux

sudo pacman -S wkhtmltopdf

From Source

If your distribution doesn’t have wkhtmltopdf in repositories:

Visit wkhtmltopdf downloads
Download the appropriate package for your distribution
Install using your package manager

Example for a .deb package:

sudo dpkg -i wkhtmltox_*.deb
sudo apt-get install -f  # Install dependencies

Configuration

Enable PDF Reports

Configure report formats in your settings.json:

{
  "analysis": {
    "report": {
      "formats": ["pdf", "html", "md"]
    }
  }
}

analysis.report.formats

array

default:"[\"pdf\", \"html\", \"md\"]"

List of output formats for generated reportsOptions:

"pdf" - PDF format (requires wkhtmltopdf)
"html" - HTML format (always available)
"md" - Markdown format (always available)

Generate Reports in Code

from openavmkit.reports import generate_report

# Generate a ratio study report
generate_report(
    locality="us-tx-travis",
    report_type="ratio_study",
    output_formats=["pdf", "html"]
)

# Generate an equity analysis report
generate_report(
    locality="us-tx-travis",
    report_type="horizontal_equity",
    output_formats=["pdf"]
)

Report Types

OpenAVM Kit can generate several types of reports:

Ratio Study

Assessment ratio analysis with COD, PRD, and other statistics

Horizontal Equity

Analysis of assessment uniformity across property types

Sales Scrutiny

Detailed examination of sales data and outliers

Model Performance

Model accuracy metrics and feature importance

All report types can be generated in PDF, HTML, and Markdown formats.

Troubleshooting

Command Not Found

Error: OSError: wkhtmltopdf command not found Solutions:

Windows

Verify wkhtmltopdf is installed in Program Files
Check that the bin directory is in your PATH
Open a new Command Prompt (PATH changes don’t affect existing terminals)
Run wkhtmltopdf --version to confirm

macOS/Linux

Check if wkhtmltopdf is installed: which wkhtmltopdf
If not found, install using your package manager
Verify installation: wkhtmltopdf --version
If installed but not found, check your PATH: echo $PATH

PDF Generation Failed

Error: Failed to generate PDF report. Is wkhtmltopdf installed? Solutions:

Verify wkhtmltopdf works directly:
```
wkhtmltopdf --version
```

Test basic PDF generation:

echo "<h1>Test</h1>" > test.html
wkhtmltopdf test.html test.pdf

Check Python can find it:

import subprocess
subprocess.run(["wkhtmltopdf", "--version"])

Look for detailed error messages in the Python traceback

Display/X11 Errors (Linux)

Error: QXcbConnection: Could not connect to display Solution: wkhtmltopdf requires X11 even for headless operation. Install xvfb:

sudo apt-get install xvfb

# Run with virtual display
xvfb-run wkhtmltopdf input.html output.pdf

Or use wkhtmltopdf with the --use-xserver flag in your configuration.

Permission Errors

Error: Permission denied when generating PDFs Solutions:

Check output directory permissions
Ensure your user has write access to the output folder
On Linux/macOS, verify file ownership:
```
ls -la out/
```

Advanced Configuration

Custom PDF Options

You can customize PDF generation by configuring wkhtmltopdf options:

from openavmkit.reports import generate_pdf

# Generate PDF with custom options
generate_pdf(
    html_content="<h1>Report</h1>",
    output_path="out/report.pdf",
    options={
        "page-size": "Letter",
        "margin-top": "0.75in",
        "margin-right": "0.75in",
        "margin-bottom": "0.75in",
        "margin-left": "0.75in",
        "encoding": "UTF-8",
        "no-outline": None,
        "enable-local-file-access": None
    }
)

Common Options

page-size

string

default:"Letter"

Page size: Letter, A4, Legal, etc.

margin-top

string

default:"0.75in"

Top margin (units: in, cm, mm)

margin-right

string

default:"0.75in"

Right margin

margin-bottom

string

default:"0.75in"

Bottom margin

margin-left

string

default:"0.75in"

Left margin

orientation

string

default:"Portrait"

Page orientation: Portrait or Landscape

enable-local-file-access

flag

Allow access to local files (needed for images, CSS)

For the full list of options, see the wkhtmltopdf documentation.

Best Practices

Generate Multiple FormatsAlways generate HTML along with PDF. HTML is useful for debugging layout issues and provides an interactive alternative to static PDFs.

{
  "analysis": {
    "report": {
      "formats": ["pdf", "html"]
    }
  }
}

Test with Simple Content FirstBefore generating complex reports, verify wkhtmltopdf works with a simple HTML file:

echo "<h1>Test Report</h1><p>This is a test.</p>" > test.html
wkhtmltopdf test.html test.pdf

Keep wkhtmltopdf UpdatedCheck for updates periodically to get bug fixes and rendering improvements:

# macOS
brew upgrade wkhtmltopdf

# Ubuntu/Debian
sudo apt-get update && sudo apt-get upgrade wkhtmltopdf

Fallback Options

If you cannot install wkhtmltopdf, you have alternatives:

Use HTML Reports

HTML reports can be:

Viewed in any web browser
Printed to PDF using the browser’s print function
Shared via web hosting
Converted to PDF using online tools

Use Markdown Reports

Markdown reports can be:

Converted to PDF using pandoc, grip, or other tools
Viewed with any text editor or Markdown viewer
Version controlled easily
Converted to other formats (Word, HTML, etc.)

Convert HTML to PDF Manually

Open the HTML report in a browser and use Print → Save as PDF:

Open out/report.html in Chrome, Firefox, or Safari
Press Ctrl+P (Cmd+P on Mac)
Select “Save as PDF” as the destination
Adjust margins and options
Click Save

Next Steps

Settings Configuration

Configure report formats and options

Analysis Guide

Learn about ratio studies and equity analysis

Cloud Storage

Share reports via cloud storage

Getting Started

Return to the getting started guide

Get Started

Core Concepts

Guides

Configuration

Advanced Topics

​Overview

​Why PDF Reports?

​Prerequisites

​Installation

​Windows

​macOS

​Linux (Debian/Ubuntu)

​Linux (Other Distributions)

​Configuration

​Enable PDF Reports

​Generate Reports in Code

​Report Types

Ratio Study

Horizontal Equity

Sales Scrutiny

Model Performance

​Troubleshooting

​Command Not Found

​PDF Generation Failed

​Display/X11 Errors (Linux)

​Permission Errors

​Advanced Configuration

​Custom PDF Options

​Common Options

​Best Practices

​Fallback Options

​Use HTML Reports

​Use Markdown Reports

​Convert HTML to PDF Manually

​Next Steps

Settings Configuration

Analysis Guide

Cloud Storage

Getting Started

Build docs developers (and LLMs) love

Overview

Why PDF Reports?

Prerequisites

Installation

Windows

macOS

Linux (Debian/Ubuntu)

Linux (Other Distributions)

Configuration

Enable PDF Reports

Generate Reports in Code

Report Types

Troubleshooting

Command Not Found

PDF Generation Failed

Display/X11 Errors (Linux)

Permission Errors

Advanced Configuration

Custom PDF Options

Common Options

Best Practices

Fallback Options

Use HTML Reports

Use Markdown Reports

Convert HTML to PDF Manually

Next Steps