learningcircuit--local-deep-research/docs/install-pip.md

# Python Package (pip) Installation Guide

> **Note:** For most users, **Docker is preferred** as it handles all dependencies automatically. pip install is best suited for **developers** or users who want to integrate LDR into existing Python projects.

## Quick Install

```bash
# Step 1: Install the package
pip install local-deep-research

# Step 2: Setup SearXNG for best results
docker pull searxng/searxng
docker run -d -p 8080:8080 --name searxng searxng/searxng

# Step 3: Install Ollama from https://ollama.ai

# Step 4: Download a model
ollama pull gemma3:12b

# Step 5: Start the web interface
ldr-web
```

Open http://localhost:5000 after a few seconds.


## SQLCipher (Database Encryption)

LDR uses SQLCipher for AES-256 encrypted databases. Pre-built `sqlcipher3` wheels are available for Windows, macOS, and Linux — most users won't need to compile anything.

- **Full setup instructions:** [SQLCipher Install Guide](SQLCIPHER_INSTALL.md)
- **Skip encryption:** If you don't need database encryption, set `export LDR_BOOTSTRAP_ALLOW_UNENCRYPTED=true` to use standard SQLite instead. API keys and data will be stored unencrypted.
- **Docker:** Includes SQLCipher out of the box — no extra setup needed.

## Optional Dependencies

### MCP Server

For integration with Claude Desktop or Claude Code:

```bash
pip install "local-deep-research[mcp]"
```

## Platform Notes

> **Windows PDF Export:** PDF export requires Pango/Cairo system libraries. See the [WeasyPrint installation guide](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html) for setup instructions.

> **CJK characters in PDF exports:** WeasyPrint resolves glyphs through the host's installed fonts. If your research results contain Chinese, Japanese, or Korean characters and they disappear from the downloaded PDF, install a CJK font package:
>
> - **Debian/Ubuntu:** `sudo apt install fonts-noto-cjk && fc-cache -fv`
> - **Fedora/RHEL:** `sudo dnf install google-noto-sans-cjk-fonts && fc-cache -fv`
> - **Alpine:** `apk add font-noto-cjk`
> - **macOS:** ships with PingFang / Hiragino — no install needed.
> - **Windows:** ships with Microsoft YaHei / SimSun — no install needed.
>
> Docker users on the official image do not need to do anything; `fonts-noto-cjk` is bundled.

> **Emoji in PDF exports:** Emojis in the markdown are rendered through the host's emoji font. If they appear as empty boxes ("tofu") in the PDF, install an emoji font package:
>
> - **Debian/Ubuntu:** `sudo apt install fonts-noto-color-emoji && fc-cache -fv`
> - **Fedora/RHEL 10+:** `sudo dnf install google-noto-color-emoji-fonts && fc-cache -fv`
> - **RHEL 9 / CentOS Stream 9:** `sudo dnf install google-noto-emoji-color-fonts && fc-cache -fv` (package was renamed to `google-noto-color-emoji-fonts` in EL10)
> - **Alpine:** `apk add font-noto-emoji` (the package name omits "color" but ships the color `NotoColorEmoji.ttf`)
> - **macOS / Windows:** ships with the OS — no install needed.
>
> Docker users on the official image do not need to do anything; `fonts-noto-color-emoji` is bundled.

## Development from Source

For contributing or running from the latest code, see the [Development Guide](developing.md).

---

[Back to Installation Overview](installation.md)