---
id: kerykeion
version: "5.12.9"
license: AGPL-3.0
license_treatment: copyleft
maintenance: active
---

# kerykeion — A Python library for astrological calculations, including natal charts, houses, planetary aspects, and SVG chart generation.

License: copyleft · Maintenance: active · Downloads: 133.6K/mo

## 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 above — 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

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

- License: AGPL-3.0 (copyleft)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 133.6K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

astrology calculations python, natal chart generator, planetary positions ephemeris, svg astrology charts, synastry chart library, astrological aspects detector, birth chart computation, astrology-calculations, svg-rendering, ephemeris

[View on SkillFed](https://skillfed.io/packages/kerykeion) · [View on PyPI](https://pypi.org/project/kerykeion/)