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

100% independent of the Swiss Ephemeris. Permissively Apache-2.0 licensed, with no Swiss Ephemeris source code, source comments, documentation prose, algorithms, distribution data files, or runtime dependency. Compatibility validation uses only public API inputs and outputs as a black box — how the stack differs. See NOTICE.md / LICENSING.md.

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; the default realization keeps positions and house angles consistent, while explicit ΔT overrides have a documented Skyfield-mode exception (details)
• Source-based validation - numerical checks use NASA JPL states, ERFA/IAU standards, cited literature, and mathematical invariants (methodology)
• 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); all 47 predefined sidereal modes operational, plus the user-defined mode, with per-mode source/audit status
• Physical planet centers when covered - outer planets use JPL center segments when available and the explicit system barycenter otherwise
• 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. The default realization is shared by positions and house angles; explicit model/user/IERS overrides affect LEB and Horizons positions but not forced Skyfield-mode positions.
• Physical planet centers - Jupiter, Saturn, Uranus, Neptune, and Pluto use JPL body-center segments where the published satellite kernels cover the requested epoch, with an explicit system-barycenter fallback outside those ranges.
• 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

Precision

Precision report · full comparison.

Numerical correctness is established from independent NASA JPL/ERFA sources, published defining conditions, and reference-free invariants.

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). Mean lunar points come from ERFA/IERS arguments; interpolated apsides use the versioned compatibility series documented in the lunar methodology. Reviewed, SHA-256-pinned medium and extended LEB2 cores are available through the normal tier download commands, while local LEB1 files remain supported.

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 (GPL-3.0-or-later components — explicit opt-in), [all] for every permissive-licensed runtime extra. 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
• Compatibility Comparison - API semantics, known differences, intentional divergences, and clean-room validation policy
• 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 - all predefined modes, source-audit status, and user mode
• 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. Published distributions beginning with 3.0.0rc3 carry this license; older distributions retain their original terms.

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 has no strong-copyleft (GPL/LGPL/AGPL) runtime dependency (all required deps are permissive except certifi's weak MPL-2.0). See THIRD_PARTY_NOTICES.md.

LibEphemeris is an independent, API-compatible implementation — see NOTICE.md. "Swiss Ephemeris" is a product of Astrodienst AG.