Kerykeion

5.12.7 · active · verified Sun Apr 12

Kerykeion is an actively developed Python library for astrological calculations, generating detailed natal charts, house positions, planetary aspects, and high-quality SVG charts. It features a data-driven approach, integrates seamlessly with LLM and AI applications for contextual astrological data, and maintains a frequent release cadence with new features in minor versions and major architectural shifts planned for new major versions.

Warnings

breaking Version 5.0.0 introduced a complete architectural redesign, replacing legacy classes (e.g., `AstrologicalSubject`, `KerykeionChartSVG`, `NatalAspects`, `SynastryAspects`) with a new factory-based system (`AstrologicalSubjectFactory`, `ChartDataFactory`, `ChartDrawer`). Direct imports and usage of old classes will break.
Fix: Migrate to the new factory-based API: use `AstrologicalSubjectFactory` to define subjects, `ChartDataFactory` to compute data, and `ChartDrawer` for rendering. Refer to the official migration guide for v4 to v5.
deprecated A backward compatibility layer (`kerykeion.backword`) was introduced in v5.0.0 to ease migration from v4 by providing wrappers for old classes. However, this layer is deprecated and will be removed entirely in v6.0.0.
Fix: Avoid using classes from `kerykeion.backword`. Update your code to use the new factory-based API directly to ensure future compatibility.
gotcha For features requiring online location lookups (e.g., city/nation to coordinates), Kerykeion relies on GeoNames. A valid GeoNames username must be provided either through the `KERYKEION_GEONAMES_USERNAME` environment variable or directly as a parameter to the factory.
Fix: Register for a free account at geonames.org and set the `KERYKEION_GEONAMES_USERNAME` environment variable with your username.
gotcha Kerykeion is licensed under the AGPL-3.0. This open-source license may require projects integrating Kerykeion's functionalities to also be open-sourced under a compatible license. Consult the LICENSE file for details.
Fix: Review the AGPL-3.0 license implications for your project. If open-sourcing your project is not feasible, consider using a compliant third-party API (like AstrologerAPI) that utilizes Kerykeion under a different commercial license.
gotcha Chart drawing offers 'classic' (default) and 'modern' styles, configurable via `ChartDrawer(style=...)` or `save_svg(style=...)`. Newer features like `show_aspect_icons` and `remove_css_variables` (for improved SVG compatibility) are optional parameters.
Fix: Explore `ChartDrawer` and `save_svg` parameters for advanced customization and compatibility options. Consult the documentation for specific version capabilities.

Install

pip install kerykeion Install stable version

Imports

AstrologicalSubjectFactory
```
from kerykeion import AstrologicalSubjectFactory
```
The AstrologicalSubject class was deprecated and replaced by AstrologicalSubjectFactory in v5.0.0.
ChartDataFactory
```
from kerykeion import ChartDataFactory
```
Part of the new v5.0.0 architecture for separating data computation.
ChartDrawer
```
from kerykeion import ChartDrawer
```
KerykeionChartSVG was deprecated and replaced by ChartDrawer in v5.0.0 for chart rendering.

Quickstart

This quickstart demonstrates how to generate a natal chart using Kerykeion's v5+ factory-based architecture. It involves creating an `AstrologicalSubjectFactory` for subject details, using `ChartDataFactory` to compute astrological data, and finally `ChartDrawer` to render the SVG chart. For online location data, a GeoNames username is required, which can be set via an environment variable. The example saves a classic-style SVG chart file.

import os
from kerykeion import AstrologicalSubjectFactory, ChartDataFactory, ChartDrawer

# Set GeoNames username for online calculations. Required for fetching city/nation coordinates.
# Register for a free account at geonames.org if you don't have one.
os.environ['KERYKEION_GEONAMES_USERNAME'] = os.environ.get('KERYKEION_GEONAMES_USERNAME', 'demo')

# 1. Create an AstrologicalSubjectFactory instance
subject_factory = AstrologicalSubjectFactory(
    name='John Doe',
    year=1990, month=5, day=15,
    hour=10, minute=30,
    city='London', nation='UK',
    gender='male'
)

# 2. Compute chart data using ChartDataFactory
chart_data_factory = ChartDataFactory(subject_factory)
natal_chart_data = chart_data_factory.make_natal_chart_data()

# 3. Draw the chart using ChartDrawer
chart_drawer = ChartDrawer(natal_chart_data)

# Generate and save the SVG chart
output_filename = 'john_doe_natal_chart.svg'
chart_drawer.save_svg(output_filename, style='classic')

print(f"Natal chart saved to {output_filename}")

# You can also get data as a Pydantic model
# print(natal_chart_data.model_dump_json(indent=2))

view raw JSON →