LibEphemeris

A high-precision astronomical ephemeris library for Python, powered by NASA JPL DE440/DE441 ephemerides and IAU 2006/2000A standards.

Drop-in replacement for PySwissEph - readable Python algorithms, standard debugging, easy deployment on the scientific Python stack (NumPy, Skyfield, pyerfa).

Features

• NASA JPL DE440/DE441 - modern planetary ephemerides via Skyfield, with full-range DE441 support for deep-history and far-future work
• IAU + Vondrák 2011 standards - long-term precession and of-date mean obliquity (Vondrák 2011, valid ±200,000 years), nutation (IAU 2006/2000A) via the official ERFA library
• Latest-reconstruction Delta T (TT−UT1) - IERS-observed values for the atomic-clock era and the most recent published reconstruction of Earth's rotation from ancient eclipse records (Stephenson, Morrison & Hohenkerk 2016 with the Morrison et al. 2021 update) for historical dates; one consistent ΔT drives positions and house angles on every backend, so a chart stays accurate and self-consistent from antiquity to the far future (details)
• Validated high precision - planetary differences typically measured in fractions of an arcsecond, house cusps < 0.02", benchmarked across 4,400+ comparison rounds (full report)
• Four backends, one API - Skyfield, LEB (~14x speedup), Horizons API, and adaptive auto mode through the same calc_ut() interface
• 25 house systems (26 codes), 47 ayanamsha modes - independently verified against pyswisseph
• Physical planet centers - outer planets corrected from barycenters using JPL satellite ephemerides
• Thread-safe contexts when you need them - SwissEph-compatible globals for drop-in migration, EphemerisContext for concurrent workloads
• 15,000+ years of coverage - base, medium, and extended precision tiers from modern use to -13200 / +17191 CE
• Readable Python 3.12+ - the ephemeris algorithms are plain, inspectable Python; clean installs across CI, containers, and serverless from prebuilt scientific wheels

Why LibEphemeris

Swiss Ephemeris is the industry standard for planetary calculations. But its Python binding (pyswisseph) wraps a large opaque C library - hard to build from source, hard to inspect or debug, tied to a single computation model.

LibEphemeris provides the same API with a modern foundation:

• NASA JPL ephemerides instead of semi-analytical theory - DE440/DE441 are the latest planetary ephemerides from the Jet Propulsion Laboratory, the same data used for spacecraft navigation.
• IAU + Vondrák 2011 standards - long-term precession and of-date mean obliquity (Vondrák, Capitaine & Wallace 2011, valid ±200,000 years instead of the IAU 2006 polynomial's few centuries), nutation (IAU 2006/2000A), all computed via the official ERFA library (the open-source implementation of IAU SOFA), not custom routines.
• Up-to-date Earth-rotation timeline (ΔT) - the TT↔UT1 conversion uses the latest published reconstruction of Earth's rotation from historical eclipse records (Stephenson-Morrison-Hohenkerk 2016 with the Morrison et al. 2021 revision), blended with IERS observations - so ancient and historical charts sit on the most current scientific ΔT, the same time argument shared by positions and house angles.
• Physical planet centers - Jupiter, Saturn, Uranus, Neptune corrected from system barycenters to actual body centers using JPL satellite ephemerides. Most libraries skip this.
• Independently verified - every function cross-validated against pyswisseph, JPL Horizons, and astropy/ERFA. Precision report with full methodology.
• Readable Python algorithms - plain, inspectable source and standard debugging instead of an opaque C library. Installs from prebuilt wheels (NumPy/Skyfield/pyerfa) across any platform, CI, or serverless environment.

Switching from pyswisseph? Your existing code works with minimal changes. Migration guide.

Accuracy over deep time

Because house cusps derive from the long-term Vondrák 2011 model (valid ±200,000 years) and houses and bodies share one obliquity and one ΔT, charts stay correct and internally self-consistent across the whole ±13,000-year ephemeris range, where a truncated precession polynomial drifts by degrees. Cusp speeds are computed as the genuine dλ/dt of the full house solution, matching the real cusp motion to < 0.005 °/day — including the iteratively-solved Placidus and Koch systems near the polar circle, where an analytic speed approximation can be off by tens to hundreds of °/day.

Methodology: Long-term sidereal time, precession & cusp speeds. Full head-to-head with Swiss Ephemeris: Swiss Ephemeris Comparison.

Quick Start

import libephemeris as swe
from libephemeris.constants import SUN, MOON, FLG_SPEED

jd = swe.julday(2000, 1, 1, 12.0)  # J2000.0

sun, _ = swe.calc_ut(jd, SUN, FLG_SPEED)
moon, _ = swe.calc_ut(jd, MOON, FLG_SPEED)

print(f"Sun:  {sun[0]:.4f} deg, speed {sun[3]:.4f} deg/day")
print(f"Moon: {moon[0]:.4f} deg, speed {moon[3]:.4f} deg/day")

# House cusps (Placidus, Rome)
cusps, ascmc = swe.houses(swe.julday(2024, 11, 5, 18.0), 41.9028, 12.4964, b"P")
print(f"ASC: {ascmc[0]:.4f}, MC: {ascmc[1]:.4f}")

For concurrent or multi-threaded workloads, use EphemerisContext instead of the module-level global state.

More examples: Getting Started

Verified Precision

Every number independently measured across 4,400+ validation rounds. Precision report · full Swiss Ephemeris comparison.

Four Backends, One API

Choose your trade-off between speed, locality, and setup. The same calc_ut() interface works across all four modes, from zero-install Horizons lookups to precomputed LEB throughput.

from libephemeris import set_calc_mode
set_calc_mode("leb")  # or via env: LIBEPHEMERIS_MODE=leb

Installation

pip install libephemeris

Out of the box, the wheel includes a bundled LEB2 base-tier core for the 14 core bodies (1850-2150). With the default medium tier, the library can auto-download the additional LEB2 data it needs on first use.

Recommended first-time setup:

libephemeris init                 # Optional but recommended interactive config
libephemeris download auto        # Download exactly what your config needs
libephemeris status               # Verify installed data and active setup

Prefer to install a tier directly? Use one of these:

libephemeris download base         # 1850-2150, lightweight
libephemeris download medium       # 1550-2650, ~200 MB (recommended)
libephemeris download extended     # -13200 to +17191 CE, full range

Optional extras: pip install libephemeris[stars] for star-catalog tooling, [nbody] for REBOUND/ASSIST n-body integration, [all] for everything. Details.

Documentation

• Getting Started - installation, ephemeris tiers, first calculations
• Migration from PySwissEph - API mapping, flag compatibility, known divergences
• Optional Modules - optional backends and extras (star catalog, n-body, SPK kernels)
• Precision Tuning - configuring optional dependencies for maximum precision
• Computation Tracing - discover which backend computed each body
• Complete API Reference - every public function, class, and constant with signatures and examples
• Precision Report - models chosen and measured accuracy for every calculation
• Swiss Ephemeris Comparison - the centralized head-to-head: precision tables, known differences, intentional divergences, API compatibility
• Long-term sidereal time, precession & cusp speeds - why houses and cusp speeds stay correct over ±13,000 years
• Delta T (ΔT) - the multi-era ΔT model (IERS + Stephenson-Morrison-Hohenkerk 2016 / Morrison 2021), why it is piecewise, and the model selector
• Flag Reference - all supported flags with examples
• House Systems - all 25 systems (26 codes) with full methodology
• Ayanamsha Modes - 47 predefined sidereal modes
• Known Bugs & Limitations - active issues and backend limitations
• LEB Binary Ephemeris - format, generation, LEB2 compression
• Horizons Backend - HTTP client, pipeline, precision
• Architecture - internal design and data flow
• Methodology - planet centers, lunar apsides, pyerfa integration
• CLI Reference - full command reference
• Changelog - release history

Contributing

git clone https://github.com/g-battaglia/libephemeris.git
cd libephemeris && uv pip install -e ".[dev]"
poe lint                           # Ruff lint + auto-fix
poe test:leb:fast                  # Recommended fast unit suite
poe test:skyfield:fast             # Skyfield backend unit suite

Part of the Kerykeion Ecosystem

LibEphemeris is the computation engine behind:

• Astrologer Studio — professional online astrology software (in production)
• Kerykeion — Python astrology library (v6 alpha)
• Astrologer API — hosted REST API for astrology data and SVG charts (upcoming)

Learn more at kerykeion.net.

License

Licensed under the Apache License 2.0 — a permissive license free for any use, including closed-source and commercial products, subject to preservation of copyright, license, and attribution notices. See LICENSING.md for details. PyPI releases carry this license.

Note: the optional libephemeris[nbody] extra pulls in rebound and assist (GPL-3.0-or-later), which are not part of the core install and are never bundled. Installing that extra makes your combined installation subject to the GPL; the core library and its required dependencies are permissive. See THIRD_PARTY_NOTICES.md.

LibEphemeris is an independent, API-compatible implementation; it contains no Swiss Ephemeris code (NOTICE.md, THIRD_PARTY_NOTICES.md). "Swiss Ephemeris" is a product of Astrodienst AG.