Computational astrology, composable by design.¶

Stellium is an extensible Python library for astrology — a fluent chart builder you configure like Lego, spanning Western, Vedic and Chinese traditions with the depth serious practitioners actually need.

pip install stellium
Launch the web app →
Open in Colab

No install required — the web app covers roughly 50–60% of the package, and Colab runs the real thing.

Two lines of code

first_chart.py¶

from stellium import ChartBuilder

chart = ChartBuilder.from_notable("Albert Einstein").with_aspects().calculate()
chart.draw("einstein.svg").save()

Albert Einstein's natal chart, drawn by Stellium

Where do you want to start?¶

Two honest paths through the same library — pick the one that sounds like you. Both lead into the same documentation; they just order it differently.

⌘ I’m a developer first

Typed, protocol-driven, composable. Feels familiar if you know React or PyTorch.

☾ I’m an astrologer first

Traditional and modern techniques, real chart output, sensible defaults out of the box.

What you can build¶

From a one-off natal wheel to a batch of 211 charts feeding a research notebook — the same library, the same objects.

☉

Natal & return charts

Publication-quality SVG wheels with dignities, fixed stars and Arabic parts — natal, solar and lunar returns, Vedic squares, Uranian dials.

☍

Relationship & timing work

Synastry, composite and Davison; transit, progression and solar-arc bi-, tri- and quad-wheels.

♃

Client-ready reports

Sectioned terminal, Markdown and HTML reports, plus typeset PDFs — with every font embedded, so they render identically on someone else’s machine.

⌘

Data & research pipelines

Serialize any chart to dict/JSON, batch thousands into a DataFrame, or feed structured chart text straight to an LLM.

Composable, not hard-coded¶

Most astrology libraries hand you one rigid constructor. Stellium hands you a builder: swap house systems, aspect engines and zodiacs, stack plugin components, and evaluate lazily — all fully typed.

composable.py¶

from stellium import ChartBuilder
from stellium.engines import ModernAspectEngine, PlacidusHouses, WholeSignHouses
from stellium.components import ArabicPartsCalculator

chart = (ChartBuilder.from_details("2000-01-06 12:00", "Seattle, WA")
    .with_house_systems([PlacidusHouses(), WholeSignHouses()])   # multiple at once
    .with_aspects(ModernAspectEngine())                          # swap the engine
    .add_component(ArabicPartsCalculator())                      # stack plugins
    .calculate())                                                # nothing ran until here

Positions come from Swiss Ephemeris. Every asteroid and trans-Neptunian body in the registry is cross-checked against NASA JPL Horizons in the test suite, so a body named Hygiea is the Hygiea. Output is portable SVG / PDF / PNG with every font bundled, so charts render identically everywhere.

Breadth most libraries skip¶

Three traditions, and the traditional timing techniques that are usually locked inside desktop software — not scattered across half a dozen half-maintained packages.

Western
Vedic · 9 ayanamsas
Chinese · Ba Zi
Synastry
Transits
Composite & Davison
Returns
Progressions
Solar arc directions
Profections
Firdaria
Zodiacal Releasing
Essential & accidental dignities
Fixed stars
Arabic parts
Uranian dials
Declinations & OOB
Primary directions
Electional
Length of life (hyleg → alcocoden)

See the chart-type catalog and the options reference for everything, with signatures.

Installation & requirements¶

One command. Every dependency — pyswisseph, pytz, geopy, rich, svgwrite, typst — is pulled in automatically, and the Swiss Ephemeris data ships inside the wheel, so there is nothing to download and no PATH to configure.

shell¶

pip install stellium

Python 3.11+
macOS · Linux · Windows
ephemeris bundled
PDF export included
no API keys

The astronomy runs with no network at all. The one exception is geocoding: passing a place name looks it up over the network, while passing coordinates does not — see Locations & time.

Learn by cookbook¶

23 runnable cookbooks holding 429 recipes — each one a focused mini-tutorial you can copy, run and adapt. Every recipe on those pages is a real function in a real script, executed at build time, showing its actual output.

Chart Visualization 21

Themes, palettes, house systems, tables.

Electional Astrology 43

Auspicious timing, predicates, planetary hours.

Profections 30

Annual and monthly profections for many points.

MultiChart 17

Synastry, transits, bi-, tri- and quad-wheels.

BaZi (Four Pillars) 23

Four Pillars, Ten Gods, hidden stems, elements.

Reports 21

Terminal reports, PDF generation, batches.

Browse all 23 cookbooks →

The complete API reference¶

Every class, method and signature — generated from source, so it is the single source of truth for the whole package. If it isn’t in a guide, it’s here.

Open the API Reference →

One chart, 15 themes¶

Restyle a whole wheel by swapping one argument — .with_theme(...). Backgrounds, zodiac rings, aspect lines and glyphs all follow. There are 49 palettes on top of that.

classic classic