kerykeion

What it is and what it does

Kerykeion is a Python library for computing astrological data and rendering charts. It wraps Swiss Ephemeris calculations (via pyswisseph) to derive planetary positions, house cusps, and aspects, then uses SVG rendering to visualize birth charts, synastry (relationship) charts, transits, composites, and returns. The library is data-driven: it exposes astrological objects (planets, houses, aspects) as structured Pydantic models, making calculations programmable and suitable for integration with APIs and AI applications.

The package supports both online and offline modes—online uses GeoNames to resolve city coordinates, while offline requires explicit longitude, latitude, and timezone. It offers customization of planets, house systems, ayanamsa modes, and chart styling. The description emphasizes a hosted API alternative for commercial or closed-source projects to sidestep AGPL copyleft concerns.

Use it for:

• Generate natal charts as SVG for astrology websites or mobile apps without server setup
• Compute synastry and composite charts to analyze relationship compatibility programmatically
• Retrieve planetary positions and aspects as JSON for integration with LLM or AI analysis workflows
• Build batch reports of transit forecasts or lunar return charts for multiple birth dates
• Embed astrological calculations in a closed-source SaaS via the hosted Astrologer API

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Kerykeion computes planetary and house positions, detects astrological aspects, and generates SVG birth, synastry, transit, and composite charts with customizable planet selections.

Yes, if you are building an open-source or AGPL-compatible astrology application and want precise, programmable chart generation. The library is actively maintained, has low install friction, and integrates cleanly with modern Python stacks. No if your project is proprietary or closed-source—use the hosted API instead. No if you need only simple zodiac sign lookups; this is a full ephemeris and rendering system.

Install

kerykeion on PyPI

pip install kerykeion

uv add kerykeion

poetry add kerykeion

Installing kerykeion

Before you install

Low install friction with a pure-Python wheel distribution. Active maintenance with a recent release and 686 GitHub stars. Eight runtime dependencies are all well-established packages (pydantic, pytz, requests, pyswisseph for ephemeris data).

License in practice

Licensed under AGPL-3.0 (copyleft). Any application that imports and uses kerykeion directly must also be AGPL-3.0 or compatible; proprietary or closed-source projects should use the hosted Astrologer API instead to avoid copyleft obligations.

Quickstart

from kerykeion import AstrologicalSubjectFactory
from kerykeion.chart_data_factory import ChartDataFactory
from kerykeion.charts.chart_drawer import ChartDrawer

subject = AstrologicalSubjectFactory.from_birth_data(
    name="Example", year=1990, month=7, day=15,
    hour=10, minute=30, lng=12.4964, lat=41.9028,
    tz_str="Europe/Rome", online=False
)
chart_data = ChartDataFactory.create_natal_chart_data(subject)
ChartDrawer(chart_data=chart_data).save_svg(output_path=".", filename="natal")

Requires Python 3.10 or higher. pyswisseph may require a C compiler on some systems; pre-built wheels are available for common platforms.

Verify before relying

• Precision claims for astrological calculations—what reference ephemeris or algorithm standard is used
• Performance characteristics for large-scale batch chart generation or API workloads
• Completeness of house system and ayanamsa (sidereal mode) implementations relative to standard astrological practice

Package facts

Evidence: kerykeion-5.12.9-py3-none-any.whl

Keywords: astrology, astrology calculations, astrology calculator, astrology library, astrology transits, astronomical algorithms, birth chart, ephemeris, houses of astrology, natal chart, planetary aspects, svg charts, synastry, zodiac, zodiac signs

Tags

More Software Development packages