Skip to main content

A python library for astrology.

Project description

Kerykeion

stars forks
PyPI Downloads PyPI Downloads contributors Package version Supported Python versions

⭐ Like this project? Star it on GitHub and help it grow! ⭐

 

Kerykeion is a Python library for astrology. It computes planetary and house positions, detects aspects, and generates SVG charts—including birth, synastry, transit, and composite charts. You can also customize which planets to include in your calculations.

The main goal of this project is to offer a clean, data-driven approach to astrology, making it accessible and programmable.

Kerykeion also integrates seamlessly with LLM and AI applications.

Here is an example of a birthchart:

John Lenon Chart

Web API

If you want to use Kerykeion in a web application, you can try the dedicated web API:

AstrologerAPI

It is open source and directly supports this project.

Donate

Maintaining this project requires substantial time and effort. The Astrologer API alone cannot cover the costs of full-time development. If you find Kerykeion valuable and would like to support further development, please consider donating:

ko-fi

Table of Contents

Installation

Kerykeion requires Python 3.9 or higher.

pip3 install kerykeion

Basic Usage

Below is a simple example illustrating the creation of an astrological subject and retrieving astrological details:

from kerykeion import AstrologicalSubject

# Create an instance of the AstrologicalSubject class.
# Arguments: Name, year, month, day, hour, minutes, city, nation
kanye = AstrologicalSubject("Kanye", 1977, 6, 8, 8, 45, "Atlanta", "US")

# Retrieve information about the Sun:
kanye.sun
# > {'name': 'Sun', 'quality': 'Mutable', 'element': 'Air', 'sign': 'Gem', 'sign_num': 2, ...}

# Retrieve information about the first house:
kanye.first_house
# > {'name': 'First_House', 'quality': 'Cardinal', 'element': 'Water', 'sign': 'Can', ...}

# Retrieve the element of the Moon sign:
kanye.moon.element
# > 'Water'

To avoid using GeoNames online, specify longitude, latitude, and timezone instead of city and nation:

kanye = AstrologicalSubject(
    "Kanye", 1977, 6, 8, 8, 45,
    lng=50,
    lat=50,
    tz_str="Europe/Rome",
    city="Rome"
)

Generate a SVG Chart

To generate a chart, use the KerykeionChartSVG class. You can create various types of charts, including birth, synastry, transit, and composite charts.

Tip: The optimized way to open the generated SVG files is with a web browser (e.g., Chrome, Firefox). To improve compatibility across different applications, you can use the remove_css_variables parameter when generating the SVG. This will inline all styles and eliminate CSS variables, resulting in an SVG that is more broadly supported.

Birth Chart

from kerykeion import AstrologicalSubject, KerykeionChartSVG

john = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
birth_chart_svg = KerykeionChartSVG(john)
birth_chart_svg.makeSVG()
birth_chart_svg.makeSVG()

The SVG file will be saved in the home directory. John Lennon Birth Chart

External Birth Chart

from kerykeion import AstrologicalSubject, KerykeionChartSVG
birth_chart = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
birth_chart_svg = KerykeionChartSVG(birth_chart, chart_type="ExternalNatal")
birth_chart_svg.makeSVG()

John Lennon External Birth Chart

Synastry Chart

from kerykeion import AstrologicalSubject, KerykeionChartSVG

first = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
second = AstrologicalSubject("Paul McCartney", 1942, 6, 18, 15, 30, "Liverpool", "GB")

synastry_chart = KerykeionChartSVG(first, "Synastry", second)
synastry_chart.makeSVG()

John Lennon and Paul McCartney Synastry

Transit Chart

from kerykeion import AstrologicalSubject

transit = AstrologicalSubject("Transit", 2025, 6, 8, 8, 45, "Atlanta", "US")
subject = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")

transit_chart = KerykeionChartSVG(subject, "Transit", transit)
transit_chart.makeSVG()

John Lennon Transit Chart

Composite Chart

from kerykeion import CompositeSubjectFactory, AstrologicalSubject, KerykeionChartSVG

angelina = AstrologicalSubject("Angelina Jolie", 1975, 6, 4, 9, 9, "Los Angeles", "US", lng=-118.15, lat=34.03, tz_str="America/Los_Angeles")

brad = AstrologicalSubject("Brad Pitt", 1963, 12, 18, 6, 31, "Shawnee", "US", lng=-96.56, lat=35.20, tz_str="America/Chicago")

factory = CompositeSubjectFactory(angelina, brad)
composite_model = factory.get_midpoint_composite_subject_model()

composite_chart = KerykeionChartSVG(composite_model, "Composite")
composite_chart.makeSVG()

Angelina Jolie and Brad Pitt Composite Chart

Wheel Only Charts

For all the charts, you can generate a wheel-only chart by using the method makeWheelOnlySVG():

Birth Chart

from kerykeion import AstrologicalSubject, KerykeionChartSVG

birth_chart = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
birth_chart_svg = KerykeionChartSVG(birth_chart)
birth_chart_svg.makeWheelOnlySVG()

John Lennon Birth Chart

Wheel Only Birth Chart (External)

from kerykeion import AstrologicalSubject, KerykeionChartSVG
birth_chart = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
birth_chart_svg = KerykeionChartSVG(birth_chart, chart_type="ExternalNatal")
birth_chart_svg.makeWheelOnlySVG(
    wheel_only=True,
    wheel_only_external=True
)

John Lennon Birth Chart

Synastry Chart

from kerykeion import AstrologicalSubject, KerykeionChartSVG
first = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
second = AstrologicalSubject("Paul McCartney", 1942, 6, 18, 15, 30, "Liverpool", "GB")
synastry_chart = KerykeionChartSVG(
    first, "Synastry", second
)
synastry_chart.makeWheelOnlySVG()

John Lennon and Paul McCartney Synastry

Change the Output Directory

To save the SVG file in a custom location, specify new_output_directory:

from kerykeion import AstrologicalSubject, KerykeionChartSVG

first = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
second = AstrologicalSubject("Paul McCartney", 1942, 6, 18, 15, 30, "Liverpool", "GB")

synastry_chart = KerykeionChartSVG(
    first, "Synastry", second,
    new_output_directory="."
)
synastry_chart.makeSVG()

Change Language

You can switch chart language by passing chart_language to the KerykeionChartSVG class:

from kerykeion import AstrologicalSubject, KerykeionChartSVG

first = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
birth_chart_svg = KerykeionChartSVG(
    birth_chart,
    chart_language="IT"  # Change to Italian
)
birth_chart_svg.makeSVG()

More details here.

The available languages are:

  • EN (English)
  • FR (French)
  • PT (Portuguese)
  • ES (Spanish)
  • TR (Turkish)
  • RU (Russian)
  • IT (Italian)
  • CN (Chinese)
  • DE (German)

Minified SVG

To generate a minified SVG, set minify_svg=True in the makeSVG() method:

from kerykeion import AstrologicalSubject, KerykeionChartSVG
first = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
birth_chart_svg = KerykeionChartSVG(birth_chart)
birth_chart_svg.makeSVG(
    minify=True
)

SVG without CSS Variables

To generate an SVG without CSS variables, set remove_css_variables=True in the makeSVG() method:

from kerykeion import AstrologicalSubject, KerykeionChartSVG

first = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")
birth_chart_svg = KerykeionChartSVG(birth_chart)
birth_chart_svg.makeSVG(
    remove_css_variables=True
)

This will inline all styles and eliminate CSS variables, resulting in an SVG that is more broadly supported.

Grid Only SVG

It's possible to generate a grid-only SVG, useful for creating a custom layout. To do this, use the makeGridOnlySVG() method:

from kerykeion import AstrologicalSubject, KerykeionChartSVG
birth_chart = AstrologicalSubject("John Lennon - Aspect Grid Dark Synastry", 1977, 6, 8, 8, 45, "Atlanta", "US")
aspect_grid_dark_synastry_chart = KerykeionChartSVG(aspect_grid_dark_synastry_subject, "Synastry", second, theme="dark")
aspect_grid_dark_synastry_chart.makeAspectGridOnlySVG()

John Lennon Birth Chart

Report

from kerykeion import Report, AstrologicalSubject

kanye = AstrologicalSubject("Kanye", 1977, 6, 8, 8, 45, "Atlanta", "US")
report = Report(kanye)
report.print_report()

Returns:

+- Kerykeion report for Kanye -+
+----------+------+-------------+-----------+----------+
| Date     | Time | Location    | Longitude | Latitude |
+----------+------+-------------+-----------+----------+
| 8/6/1977 | 8:45 | Atlanta, US | -84.38798 | 33.749   |
+----------+------+-------------+-----------+----------+
+-----------------+------+-------+------+----------------+
| Planet          | Sign | Pos.  | Ret. | House          |
+-----------------+------+-------+------+----------------+
| Sun             | Gem  | 17.6  | -    | Twelfth_House  |
| Moon            | Pis  | 16.43 | -    | Ninth_House    |
| Mercury         | Tau  | 26.29 | -    | Eleventh_House |
| Venus           | Tau  | 2.03  | -    | Tenth_House    |
| Mars            | Tau  | 1.79  | -    | Tenth_House    |
| Jupiter         | Gem  | 14.61 | -    | Eleventh_House |
| Saturn          | Leo  | 12.8  | -    | Second_House   |
| Uranus          | Sco  | 8.27  | R    | Fourth_House   |
| Neptune         | Sag  | 14.69 | R    | Fifth_House    |
| Pluto           | Lib  | 11.45 | R    | Fourth_House   |
| Mean_Node       | Lib  | 21.49 | R    | Fourth_House   |
| True_Node       | Lib  | 22.82 | R    | Fourth_House   |
| Mean_South_Node | Ari  | 21.49 | R    | Tenth_House    |
| True_South_Node | Ari  | 22.82 | R    | Tenth_House    |
| Chiron          | Tau  | 4.17  | -    | Tenth_House    |
+-----------------+------+-------+------+----------------+
+----------------+------+----------+
| House          | Sign | Position |
+----------------+------+----------+
| First_House    | Can  | 18.0     |
| Second_House   | Leo  | 9.51     |
| Third_House    | Vir  | 4.02     |
| Fourth_House   | Lib  | 3.98     |
| Fifth_House    | Sco  | 9.39     |
| Sixth_House    | Sag  | 15.68    |
| Seventh_House  | Cap  | 18.0     |
| Eighth_House   | Aqu  | 9.51     |
| Ninth_House    | Pis  | 4.02     |
| Tenth_House    | Ari  | 3.98     |
| Eleventh_House | Tau  | 9.39     |
| Twelfth_House  | Gem  | 15.68    |
+----------------+------+----------+

To export to a file:

```bash
python3 your_script_name.py > file.txt

Example: Retrieving Aspects

from kerykeion import SynastryAspects, AstrologicalSubject

first = AstrologicalSubject("Jack", 1990, 6, 15, 15, 15, "Roma", "IT")
second = AstrologicalSubject("Jane", 1991, 10, 25, 21, 0, "Roma", "IT")

name = SynastryAspects(first, second)
aspect_list = name.get_relevant_aspects()
print(aspect_list[0])
#> {'p1_name': 'Sun', 'p1_abs_pos': 84.17867971515636, 'p2_name': 'Sun', 'p2_abs_pos': 211.90472999502984, 'aspect': 'trine', 'orbit': 7.726050279873476, 'aspect_degrees': 120, 'color': '#36d100', 'aid': 6, 'diff': 127.72605027987348, 'p1': 0, 'p2': 0}

Ayanamsa (Sidereal Modes)

By default, the zodiac type is Tropical. To use Sidereal, specify the sidereal mode:

johnny = AstrologicalSubject(
    "Johnny Depp", 1963, 6, 9, 0, 0,
    "Owensboro", "US",
    zodiac_type="Sidereal",
    sidereal_mode="LAHIRI"
)

More examples here.

Full list of supported sidereal modes here.

House Systems

By default, houses are calculated using Placidus. Configure a different house system as follows:

johnny = AstrologicalSubject(
    "Johnny Depp", 1963, 6, 9, 0, 0,
    "Owensboro", "US",
    houses_system="M"
)

More examples here.

Full list of supported house systems here.

So far all the available houses system in the Swiss Ephemeris are supported but the Gauquelin Sectors.

Perspective Type

By default, Kerykeion uses the Apparent Geocentric perspective (the most standard in astrology). Other perspectives (e.g., Heliocentric) can be set this way:

johnny = AstrologicalSubject(
    "Johnny Depp", 1963, 6, 9, 0, 0,
    "Owensboro", "US",
    perspective_type="Heliocentric"
)

More examples here.

Full list of supported perspective types here.

Themes

Kerykeion provides several chart themes:

  • Classic (default)
  • Dark
  • Dark High Contrast
  • Light

Each theme offers a distinct visual style, allowing you to choose the one that best suits your preferences or presentation needs. If you prefer more control over the appearance, you can opt not to set any theme, making it easier to customize the chart by overriding the default CSS variables. For more detailed instructions on how to apply themes, check the documentation

Here's an example of how to set the theme:

from kerykeion import AstrologicalSubject, KerykeionChartSVG

dark_theme_subject = AstrologicalSubject("John Lennon - Dark Theme", 1940, 10, 9, 18, 30, "Liverpool", "GB")
dark_theme_natal_chart = KerykeionChartSVG(dark_high_contrast_theme_subject, theme="dark_high_contrast")
dark_theme_natal_chart.makeSVG()

John Lennon

Alternative Initialization

Create an AstrologicalSubject from a UTC ISO 8601 string:

subject = AstrologicalSubject.get_from_iso_utc_time(
    "Johnny Depp", "1963-06-09T05:00:00Z", "Owensboro", "US"
)

If you set online=True, provide a geonames_username to allow city-based geolocation:

from kerykeion.astrological_subject import AstrologicalSubject

subject = AstrologicalSubject.get_from_iso_utc_time(
    "Johnny Depp", "1963-06-09T05:00:00Z", "Owensboro", "US", online=True
)

Lunar Nodes (Rahu & Ketu)

Kerykeion supports both True and Mean Lunar Nodes:

  • True North Lunar Node: "true_node" (name kept without "north" for backward compatibility).
  • True South Lunar Node: "true_south_node".
  • Mean North Lunar Node: "mean_node" (name kept without "north" for backward compatibility).
  • Mean South Lunar Node: "mean_south_node".

In instances of the AstrologicalSubject class, all of them are active by default.

In instances of the classes used to generate aspects and SVG charts, only the mean nodes are active. To activate the true nodes, you need to pass the active_points parameter to the KerykeionChartSVG class.

Example:

from kerykeion import AstrologicalSubject, KerykeionChartSVG

subject = AstrologicalSubject("John Lennon", 1940, 10, 9, 18, 30, "Liverpool", "GB")

chart = KerykeionChartSVG(
    subject,
    active_points=[
        "Sun", 
        "Moon", 
        "Mercury", 
        "Venus", 
        "Mars", 
        "Jupiter", 
        "Saturn",
        "Uranus", 
        "Neptune", 
        "Pluto", 
        "Mean_Node", 
        "Mean_South_Node", 
        "True_Node",       # Activates True North Node 
        "True_South_Node", # Activates True South Node
        "Ascendant",
        "Medium_Coeli", 
        "Descendant", 
        "Imum_Coeli"
    ]
)
chart.makeSVG()

JSON Support

You can serialize the astrological subject (the base data used throughout the library) to JSON:

from kerykeion import AstrologicalSubject

johnny = AstrologicalSubject("Johnny Depp", 1963, 6, 9, 0, 0, "Owensboro", "US")

print(johnny.json(dump=False, indent=2))

Auto Generated Documentation

You can find auto-generated documentation here. Most classes and functions include docstrings.

Development

Clone the repository or download the ZIP via the GitHub interface.

Integrating Kerykeion into Your Project

If you would like to incorporate Kerykeion’s astrological features into your application, please reach out via email. Whether you need custom features, support, or specialized consulting, I am happy to discuss potential collaborations.

License

This project is covered under the AGPL-3.0 License. For detailed information, please see the LICENSE file. If you have questions, feel free to contact me at kerykeion.astrology@gmail.com.

As a rule of thumb, if you use this library in a project, you should open-source that project under a compatible license. Alternatively, if you wish to keep your source closed, consider using the AstrologerAPI, which is AGPL-3.0 compliant and also helps support the project.

Since the AstrologerAPI is an external third-party service, using it does not require your code to be open-source.

Contributing

Contributions are welcome! Feel free to submit pull requests or report issues.

Citations

If using Kerykeion in published or academic work, please cite as follows:

Battaglia, G. (2025). Kerykeion: A Python Library for Astrological Calculations and Chart Generation.
https://github.com/g-battaglia/kerykeion

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

kerykeion-4.26.2.tar.gz (379.1 kB view details)

Uploaded Source

Built Distribution

kerykeion-4.26.2-py3-none-any.whl (396.9 kB view details)

Uploaded Python 3

File details

Details for the file kerykeion-4.26.2.tar.gz.

File metadata

  • Download URL: kerykeion-4.26.2.tar.gz
  • Upload date:
  • Size: 379.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.5 CPython/3.13.1 Darwin/24.2.0

File hashes

Hashes for kerykeion-4.26.2.tar.gz
Algorithm Hash digest
SHA256 7f094118883c6b8d524e362c965caf5842aecb7739fd08387939c39e62d89276
MD5 0bc961c3f4bee40fdd320cca0f940c41
BLAKE2b-256 1b49f8b955eb3459e49844265e394561e8428a698eb4c9d41bd6b8966fae7998

See more details on using hashes here.

File details

Details for the file kerykeion-4.26.2-py3-none-any.whl.

File metadata

  • Download URL: kerykeion-4.26.2-py3-none-any.whl
  • Upload date:
  • Size: 396.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.5 CPython/3.13.1 Darwin/24.2.0

File hashes

Hashes for kerykeion-4.26.2-py3-none-any.whl
Algorithm Hash digest
SHA256 3444e2df2b62aa470f40e907aabc20993f6b8b4afb0599eb1272b61694d067db
MD5 98e6d59f1d90ff21bb52db91ea03b35b
BLAKE2b-256 84aecd2c87324056278b416a8da4ec94422af8933fe0ed5a0464e1e925b78fdb

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page