Skip to content

Installation

Just want to get started?

If you just want to create your blog, check out our Quick Start Guide which covers installation in simple steps.

This page contains detailed installation instructions for developers and power users.

Egregora requires Python 3.12+ and uses uv for package management.

Install uv

First, install uv if you haven't already:

1
curl -LsSf https://astral.sh/uv/install.sh | sh

1
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Install Egregora

Install the latest version directly from the repository:

1
uv tool install git+https://github.com/franklinbaldo/egregora

Once installed, you can use the egregora command directly:

1
2
3
4
5
# Initialize a new blog
egregora init my-blog

# Process WhatsApp export
egregora write export.zip

From PyPI (Stable)

1
uv tool install egregora

From Source

For development (works on Windows, Linux, and macOS):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
git clone https://github.com/franklinbaldo/egregora.git
cd egregora

# Quick setup (installs dependencies + pre-commit hooks)
python dev_tools/setup_hooks.py

# Or manual setup
uv sync --all-extras
uv run pre-commit install

# Run tests
uv run pytest tests/

See Contributing Guide for full development setup.

API Key Setup

Egregora uses Google's Gemini API for content generation. Get a free API key at https://ai.google.dev/gemini-api/docs/api-key.

1
export GOOGLE_API_KEY="your-google-gemini-api-key"

1
$Env:GOOGLE_API_KEY = "your-google-gemini-api-key"

Verify Installation

Test that everything is working:

1
egregora --version

Optional Dependencies

Documentation

To build the documentation locally:

1
2
# Preview your site
uv tool run --from "git+https://github.com/franklinbaldo/egregora[mkdocs]" mkdocs serve -f .egregora/mkdocs.yml

Next Steps