The Python Astrology Library
Kerykeion computes natal charts, synastry, transits and returns, then renders publication-quality SVG charts. Type-safe, offline-capable, built on LibEphemeris, our own high-precision engine.
Over 2 million PyPI downloads · used in research and production worldwide
Why Developers Choose Kerykeion
A modern, type-safe astrology engine designed to be reused, audited and extended.
Beautiful Charts
Fast SVG rendering with themes, i18n, wheel-only and grid-only modes
Data First
Factory architecture separates calculations from rendering for clarity and testability
Precise Astronomy
LibEphemeris under the hood: sub-arcsecond precision from NASA JPL data
Type-Safe Models
Pydantic 2 data classes for subjects, aspects, distributions, and returns
Flexible Analysis
Natal, synastry, transit, composite, solar and lunar returns
Works Offline
Provide lng, lat, and tz_str to avoid network calls entirely
Quick Example
From birth data to a rendered SVG chart in a few lines.
from pathlib import Path
from kerykeion import AstrologicalSubjectFactory
from kerykeion.chart_data_factory import ChartDataFactory
from kerykeion.charts.chart_drawer import ChartDrawer
# Create a subject from birth data (offline example with manual coordinates)
subject = AstrologicalSubjectFactory.from_birth_data(
"Kanye", 1977, 6, 8, 8, 45,
lng=-84.38798,
lat=33.7490,
tz_str="America/New_York",
online=False,
)
# Pre-compute natal chart data (calculations only)
chart_data = ChartDataFactory.create_natal_chart_data(subject)
# Render and save the SVG
drawer = ChartDrawer(chart_data=chart_data)
out_dir = Path("charts_output")
out_dir.mkdir(exist_ok=True)
drawer.save_svg(output_path=out_dir, filename="kanye-natal")
Features At A Glance
Calculations
- Planet and point positions (with daily motion and declination)
- Houses with multiple systems (default: Placidus)
- True/Mean Nodes, Lilith, Chiron, angles, asteroids and TNOs
- Single-chart and dual-chart aspects with orb controls
Analysis
- Element and quality distributions (weighted or pure-count)
- Customizable weighting per point with fallback
- Synastry extras: relationship score and house overlays
Rendering
- Full charts, wheel-only, or aspect-grid-only as SVG
- Themes: classic, dark, light, strawberry, dark-high-contrast, black-and-white
- Internationalization: EN, FR, PT, ES, TR, RU, IT, CN, DE
Configuration
- Tropical or Sidereal (e.g., LAHIRI) zodiac
- House systems (Placidus default, others supported)
- Multiple perspective types (Geocentric, Heliocentric, etc.)
AI-Ready Astrological Context
The context_serializer module
turns complex charts into precise, hallucination-free text ready to drop into an LLM prompt.
Optimized for LLMs
Structured output designed to be injected directly into system prompts for GPT, Claude, and others.
Every Chart Type
Natal, synastry, composite, transit and return charts. Consistent, type-safe descriptions.
Chart for John Doe
Birth data: 1990-01-01 12:00, London, GB
Coordinates: 51.51°N, -0.13°W
Zodiac system: Tropical · House system: Placidus
Celestial Points:
- Sun at 10.81° in Capricorn in Tenth House
quality: Cardinal, element: Earth
- Moon at 25.60° in Aquarius in Eleventh House
quality: Fixed, element: Air
... Showcase
Examples of the charts you can generate.
Licensing & Commercial Use
Kerykeion is AGPL-3.0. Link the library and your app must be open-source under a compatible license. Need to keep your source closed? Consume Kerykeion as an external service via the hosted Astrologer API.
Library (AGPL-3.0)
Open Source
Use freely in compatible open-source projects. All calculations open and auditable.
Hosted API
CommercialCommercial Use
Keep your source closed: consume Kerykeion as an external REST service via the Astrologer API.
Start building with Kerykeion
Install the library, read the docs, and generate your first chart in minutes.