Install & Compatibility
Where this runs
tested against v5.12.9 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.12
✕ build_error
✕ build_error
py 3.13
✕ build_error
✕ build_error
48MB installed
● package 48MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AstrologicalSubjectFactory
✓ from kerykeion import AstrologicalSubjectFactory
✗ from kerykeion import AstrologicalSubject
The AstrologicalSubject class was deprecated and replaced by AstrologicalSubjectFactory in v5.0.0.
ChartDataFactory
✓ from kerykeion import ChartDataFactory
Part of the new v5.0.0 architecture for separating data computation.
ChartDrawer
✓ from kerykeion import ChartDrawer
✗ from kerykeion import KerykeionChartSVG
KerykeionChartSVG was deprecated and replaced by ChartDrawer in v5.0.0 for chart rendering.
This quickstart demonstrates how to generate a natal chart using Kerykeion's v5+ factory-based architecture. It involves creating an `AstrologicalSubjectFactory` for subject details, using `ChartDataFactory` to compute astrological data, and finally `ChartDrawer` to render the SVG chart. For online location data, a GeoNames username is required, which can be set via an environment variable. The example saves a classic-style SVG chart file.
import os
from kerykeion import AstrologicalSubjectFactory, ChartDataFactory, ChartDrawer
# Set GeoNames username for online calculations. Required for fetching city/nation coordinates.
# Register for a free account at geonames.org if you don't have one.
os.environ['KERYKEION_GEONAMES_USERNAME'] = os.environ.get('KERYKEION_GEONAMES_USERNAME', 'demo')
# 1. Create an AstrologicalSubjectFactory instance
subject_factory = AstrologicalSubjectFactory(
name='John Doe',
year=1990, month=5, day=15,
hour=10, minute=30,
city='London', nation='UK',
gender='male'
)
# 2. Compute chart data using ChartDataFactory
chart_data_factory = ChartDataFactory(subject_factory)
natal_chart_data = chart_data_factory.make_natal_chart_data()
# 3. Draw the chart using ChartDrawer
chart_drawer = ChartDrawer(natal_chart_data)
# Generate and save the SVG chart
output_filename = 'john_doe_natal_chart.svg'
chart_drawer.save_svg(output_filename, style='classic')
print(f"Natal chart saved to {output_filename}")
# You can also get data as a Pydantic model
# print(natal_chart_data.model_dump_json(indent=2))
kerykeion --version
Debug
Known issues
breakingVersion 5.0.0 introduced a complete architectural redesign, replacing legacy classes (e.g., `AstrologicalSubject`, `KerykeionChartSVG`, `NatalAspects`, `SynastryAspects`) with a new factory-based system (`AstrologicalSubjectFactory`, `ChartDataFactory`, `ChartDrawer`). Direct imports and usage of old classes will break.fixMigrate to the new factory-based API: use `AstrologicalSubjectFactory` to define subjects, `ChartDataFactory` to compute data, and `ChartDrawer` for rendering. Refer to the official migration guide for v4 to v5.
affects: >=5.0.0
deprecatedA backward compatibility layer (`kerykeion.backword`) was introduced in v5.0.0 to ease migration from v4 by providing wrappers for old classes. However, this layer is deprecated and will be removed entirely in v6.0.0.fixAvoid using classes from `kerykeion.backword`. Update your code to use the new factory-based API directly to ensure future compatibility.
affects: 5.0.0 - 5.x.x (will be removed in v6.0.0)
gotchaFor features requiring online location lookups (e.g., city/nation to coordinates), Kerykeion relies on GeoNames. A valid GeoNames username must be provided either through the `KERYKEION_GEONAMES_USERNAME` environment variable or directly as a parameter to the factory.fixRegister for a free account at geonames.org and set the `KERYKEION_GEONAMES_USERNAME` environment variable with your username.
affects: All versions (where online features are used)
gotchaKerykeion is licensed under the AGPL-3.0. This open-source license may require projects integrating Kerykeion's functionalities to also be open-sourced under a compatible license. Consult the LICENSE file for details.fixReview the AGPL-3.0 license implications for your project. If open-sourcing your project is not feasible, consider using a compliant third-party API (like AstrologerAPI) that utilizes Kerykeion under a different commercial license.
affects: All versions
gotchaChart drawing offers 'classic' (default) and 'modern' styles, configurable via `ChartDrawer(style=...)` or `save_svg(style=...)`. Newer features like `show_aspect_icons` and `remove_css_variables` (for improved SVG compatibility) are optional parameters.fixExplore `ChartDrawer` and `save_svg` parameters for advanced customization and compatibility options. Consult the documentation for specific version capabilities.
affects: >=5.11.0
Errors
Common errors & fixes
TypeError: 'type' object is not subscriptable
This error often occurs when using built-in types like `list` or `dict` as generic types (e.g., `list[str]`) in type hints with Python versions older than 3.9, or when attempting to subscript a type object that is not a generic type.
fixEnsure you are running Python 3.9 or higher as required by kerykeion. If the error persists, use `typing.List` or `typing.Dict` from the `typing` module for generic type hints, or check the library's documentation for correct type usage in its API.
Permission error "write a readonly database"
The kerykeion library, which uses Swiss Ephemeris, attempts to write or update data files but lacks the necessary file system permissions in the directory where it's trying to store its database.
fixGrant write permissions to the user running the Python script in the directory where kerykeion stores its data (typically a `.kerykeion` folder in the user's home directory or a system-wide location), or run the script with elevated privileges if appropriate for your environment.
AttributeError: 'KerykeionChartSVG' object has no attribute 'aspects_list'
Users attempting to access astrological aspects directly from a `KerykeionChartSVG` object, which is primarily for generating SVG charts. The aspects data is typically part of the `AstrologicalSubject` or `ChartDataFactory` output, not directly on the SVG generation object.
fixAccess aspects from the `AstrologicalSubject` instance or the data returned by methods like `get_relevant_aspects()` on a `SynastryAspects` object, or within the `ChartDataFactory` output, rather than the `KerykeionChartSVG` object. For example, `subject.get_all_aspects()` or `SynastryAspects(subject1, subject2).get_relevant_aspects()`.
unexpected keyword argument 'lang'
This error occurs when passing an unsupported keyword argument named 'lang' directly to a kerykeion class constructor or function that does not accept it. Language settings are often managed through separate functions or different parameters.
fixRemove the `lang` keyword argument from the constructor or function call. If you intend to change the language, use the appropriate language setting mechanism provided by the library, such as `kerykeion.settings.set_language()` or a dedicated `change_language()` function if available, which operates on the overall settings rather than an individual object's initialization.
Upgrade
Version history
5.12.9latest on PyPI · released May 25, 2026
Audit
Dependencies
pydanticrequiredData modeling and validation
pytzrequiredTimezone handling
svgwriterequiredSVG chart generation
requestsrequiredFetching external data (e.g., GeoNames)
numpyrequiredNumerical operations
skyfieldrequiredAstronomical calculations
ephemrequiredAstronomical calculations