Install & Compatibility
Where this runs
tested against v2.24 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.246s · 89.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.7s · import 0.278s · 86MB
90MB installed
● package 90MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Ephemeris
✓ from jplephem.ephem import Ephemeris
Used for loading and interpolating from standard JPL DE (.bsp) kernels.
SPK
✓ from jplephem.spk import SPK
Used for loading and interpolating from SPK (.bsp) kernels, often used for spacecraft and smaller bodies.
convert_datetime_to_jd
✓ from jplephem.jpllib import convert_datetime_to_jd
Helper function to convert Python datetime objects to Julian Dates, which are used internally by jplephem.
This quickstart demonstrates how to load a JPL ephemeris (.bsp) file and compute the position and velocity of a celestial body. **Crucially, the .bsp file itself is NOT bundled with the library and must be downloaded separately.** Common files like `de421.bsp` or `de440.bsp` can be found on JPL's FTP server. The example checks for the file specified by the `JPLEPHEM_BSP_PATH` environment variable (defaulting to 'de421.bsp' in the current directory) and proceeds with a calculation if found, otherwise it prints an explanatory error.
import os
from datetime import datetime
from jplephem.ephem import Ephemeris
from jplephem.jpllib import convert_datetime_to_jd
# WARNING: Ephemeris data files are large and NOT bundled with the library.
# You must download a JPL .bsp ephemeris file (e.g., 'de421.bsp' or 'de440.bsp')
# from the JPL FTP server (ftp://ssd.jpl.nasa.gov/pub/eph/planets/bsp/)
# or NASA PDS (https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/).
#
# Set the environment variable JPLEPHEM_BSP_PATH to the path of your downloaded file.
# For example: export JPLEPHEM_BSP_PATH="/path/to/your/de421.bsp"
bsp_path = os.environ.get('JPLEPHEM_BSP_PATH', 'de421.bsp')
if not os.path.exists(bsp_path):
print(f"Error: Ephemeris file '{bsp_path}' not found.")
print("Please download a .bsp kernel (e.g., de421.bsp) and set the")
print("JPLEPHEM_BSP_PATH environment variable, or place the file in the current directory.")
print("Skipping ephemeris calculation.")
else:
try:
ephemeris = Ephemeris(bsp_path)
print(f"Successfully loaded ephemeris from: {bsp_path}")
# Calculate position of Earth-Moon Barycenter (body 3) relative to
# Solar System Barycenter (body 0) on January 1, 2000.
target_date = datetime(2000, 1, 1, 12, 0, 0) # Noon UTC
jd = convert_datetime_to_jd(target_date)
# The 'observer' is the body from which the 'target' is observed.
# Here, observer=0 (Solar System Barycenter), target=3 (Earth-Moon Barycenter).
# The result is a 3-element NumPy array: [x, y, z] in AU.
position_vector = ephemeris.position(3, 0, jd)
print(f"\nDate: {target_date.isoformat()}")
print(f"Julian Date: {jd}")
print(f"Position of Earth-Moon Barycenter relative to SSB (AU):")
print(f" x={position_vector[0]:.6f}, y={position_vector[1]:.6f}, z={position_vector[2]:.6f}")
# Example with velocity:
velocity_vector = ephemeris.velocity(3, 0, jd)
print(f"Velocity of Earth-Moon Barycenter relative to SSB (AU/day):")
print(f" vx={velocity_vector[0]:.6f}, vy={velocity_vector[1]:.6f}, vz={velocity_vector[2]:.6f}")
except Exception as e:
print(f"An error occurred while using the ephemeris: {e}")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'jplephem.pck'
This error typically occurs when Skyfield, which depends on jplephem, requires a newer version of jplephem than is currently installed. The 'pck' module was introduced in jplephem versions greater than 2.11.
fixUpgrade jplephem to the latest version using pip: `pip install -U jplephem`.
ValueError: SPK data type X not yet supported.
The specific SPK (Spacecraft Planet Kernel) data type (e.g., Type 1, Type 21) within the .bsp ephemeris file is not currently implemented or supported by the jplephem library.
fixUse a .bsp ephemeris file that contains supported SPK data types (such as Type 2, Type 3, or Type 9). Refer to jplephem documentation or release notes for supported types, or consider using other tools if unsupported types are critical.
FileNotFoundError: [Errno 2] No such file or directory: 'de4xx.bsp'
The program cannot find the specified .bsp ephemeris file because it either does not exist, is not in the expected directory, or the path provided is incorrect.
fixEnsure that the .bsp ephemeris file (e.g., 'de430.bsp') has been downloaded and is placed in the same directory as your Python script, or provide the full and correct file path to `SPK.open()` or `Ephemeris()` methods.
ValueError: Julian date X out of range Y..Z
The Julian date provided for the ephemeris calculation falls outside the valid time span covered by the loaded ephemeris file or the specific segment within it.
fixVerify the requested Julian date is within the range of the ephemeris file. You can inspect the `start_jd` and `end_jd` attributes of the kernel's segments to determine the valid date ranges.
Upgrade
Version history
2.24latest on PyPI · released Jan 23, 2026
Audit
Dependencies
numpyrequiredRequired for numerical array operations and calculations.