Kerykeion is a modern, type-safe Python library for astrology. It computes natal charts, synastry, transits, and renders beautiful SVG birth charts. Used by developers worldwide to build astrology apps and services.

Is Kerykeion free to use?

Yes! Kerykeion is open-source and licensed under AGPL-3.0. You can use it freely in open-source projects. For closed-source commercial use, you can use the Astrologer API which provides the same calculations via REST endpoints.

How do I install Kerykeion?

Install via pip: pip install kerykeion. The library requires Python 3.9+ and has minimal dependencies. Full documentation is available in our docs section.

What is the Astrologer API?

The Astrologer API is a hosted REST API built on Kerykeion. It provides all the astrology calculations without requiring you to manage Python infrastructure or open-source your code. Available on RapidAPI with free and paid tiers.

Can I use Kerykeion in commercial projects?

If your project is open-source with an AGPL-compatible license, yes. For proprietary/closed-source projects, use the Astrologer API instead — it's AGPL-compliant and supports the project development.

What chart types are supported?

Kerykeion supports natal charts, synastry (relationship compatibility), composite charts, transit charts, solar returns, and lunar returns. All charts can be rendered as SVG with customizable themes.

Try Astrologer API

Subscribe to support and grow the project.

Kerykeion

Data Driven
Astrology 💫

Compute precise astrological data, detect aspects, and render beautiful SVG charts with a modern, type-safe Python library.

Documentation Examples

Try Astrologer API

Implement the kerykeion functionality in your free or commercial app quickly and hassle-free.
Subscribing helps support the project and keeps it growing!

Subscribe Now Learn More

Professional Astrology Suite

Discover Astrologer Studio

A complete professional astrology environment and client management system. Generate high-precision charts, manage your clients, and get AI-powered insights.
Built on Kerykeion technology, designed for professional astrologers.

Try Now Free Birth Chart

Astrologer Studio - Birth Chart Screenshot

Why Developers Choose Kerykeion

A modern, type-safe Python library designed for precision astrology calculations and beautiful chart rendering.

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

Swiss Ephemeris (NASA JPL) under the hood for positions, motion, and declination

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

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

Swiss Ephemeris (NASA JPL) under the hood for positions, motion, and declination

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

Build an AstrologicalSubject

Create a subject from birth or event data. You can use offline coordinates or leverage the built-in GeoNames integration for automatic lookup.

Use ChartDataFactory

Generate all necessary astronomical calculations, including planetary positions, house cusps, aspects, and element distributions.

Render an SVG

Visualize the data using ChartDrawer to create beautiful, customizable SVG charts, or generate detailed text reports.

Hosted Solution

Upgrade Path — AstrologerAPI

Building a commercial or closed-source app? Prefer serverless scale and language-agnostic integration? Use the hosted API.

License friendly: keep your app closed-source

Language agnostic: Python, JS/TS, Go, Rust, Swift

Zero ops: no ephemeris files or timezone edge cases

Supports the project: API revenue funds development

Try AstrologerAPI View API Source

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, 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.)

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, 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.)

New Feature

AI-Ready Astrological Context

Bridge the gap between raw astrological data and Large Language Models. The new context_serializer module transforms complex charts into precise, hallucination-free text descriptions optimized for AI consumption.

Optimized for LLMs

Structured, non-qualitative output designed to be injected directly into system prompts for ChatGPT, Claude, and other models.

Comprehensive Support

Works with Natal, Synastry, Composite, Transit, and Return charts. Get consistent, type-safe descriptions for any astrological subject.

Read Documentation View on GitHub

System Prompt ExampleJSON / Text

Chart for John Doe
Birth data: 1990-01-01 12:00, London, GB
Coordinates: 51.51°N, -0.13°W
Timezone: Europe/London
Zodiac system: Tropical
House system: Placidus

Celestial Points:
  - Sun at 10.81° in Capricorn in Tenth House
    quality: Cardinal, element: Earth
    direct motion, speed 1.0195°/day
  - Moon at 25.60° in Aquarius in Eleventh House
    quality: Fixed, element: Air
    direct motion, speed 12.4796°/day
  ...

AI Ready

Showcase

Here are some examples of the charts you can generate.

Common Use Cases

Product features: embeddable charts and reports

Research & analytics: programmatic aspect mining

Publishing: B/W theme for crisp prints and PDFs

Generative AI: structured JSON models and SVGs

Product features: embeddable charts and reports

Research & analytics: programmatic aspect mining

Publishing: B/W theme for crisp prints and PDFs

Generative AI: structured JSON models and SVGs

Licensing & Commercial Use

Kerykeion is AGPL-3.0. If you link the library in your app, your app must be open-source under a compatible license. If you need to keep your source closed, use the hosted AstrologerAPI — it's AGPL-compliant and supports the project.

Hosted API

Recommended

Commercial Use

Integrate in closed-source and commercial applications without licensing concerns

Library (AGPL-3.0)

Open Source

Use freely in compatible open-source projects

Hosted API

Recommended

Commercial Use

Integrate in closed-source and commercial applications without licensing concerns

Library (AGPL-3.0)

Open Source

Use freely in compatible open-source projects

Frequently Asked Questions

Current Transits

Current planetary positions and lunar phase

Planet	Position	Sign	Speed	Declination








Name Phase Day

Learn Astrology

Master the symbolic language of the stars with our comprehensive collection of 300+ free guides. From birth charts to transits, start your journey today.