{"id":5267,"library":"jplephem","title":"jplephem: JPL Planetary Ephemeris Access","description":"jplephem (version 2.24) is a Python library that enables users to load and interpolate positions and velocities from JPL Planetary and Lunar Ephemerides (.bsp files). It provides a programmatic interface to NASA JPL's highly accurate ephemeris data, often used in astronomy and astrodynamics. The library is actively maintained with releases occurring as needed for updates or bug fixes.","status":"active","version":"2.24","language":"en","source_language":"en","source_url":"https://github.com/brandon-rhodes/python-jplephem/","tags":["astronomy","ephemeris","jpl","celestial mechanics","solar system","astrodynamics","numpy"],"install":[{"cmd":"pip install jplephem","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for numerical array operations and calculations.","package":"numpy"}],"imports":[{"note":"Used for loading and interpolating from standard JPL DE (.bsp) kernels.","symbol":"Ephemeris","correct":"from jplephem.ephem import Ephemeris"},{"note":"Used for loading and interpolating from SPK (.bsp) kernels, often used for spacecraft and smaller bodies.","symbol":"SPK","correct":"from jplephem.spk import SPK"},{"note":"Helper function to convert Python datetime objects to Julian Dates, which are used internally by jplephem.","symbol":"convert_datetime_to_jd","correct":"from jplephem.jpllib import convert_datetime_to_jd"}],"quickstart":{"code":"import os\nfrom datetime import datetime\nfrom jplephem.ephem import Ephemeris\nfrom jplephem.jpllib import convert_datetime_to_jd\n\n# WARNING: Ephemeris data files are large and NOT bundled with the library.\n# You must download a JPL .bsp ephemeris file (e.g., 'de421.bsp' or 'de440.bsp')\n# from the JPL FTP server (ftp://ssd.jpl.nasa.gov/pub/eph/planets/bsp/)\n# or NASA PDS (https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/).\n#\n# Set the environment variable JPLEPHEM_BSP_PATH to the path of your downloaded file.\n# For example: export JPLEPHEM_BSP_PATH=\"/path/to/your/de421.bsp\"\n\nbsp_path = os.environ.get('JPLEPHEM_BSP_PATH', 'de421.bsp')\n\nif not os.path.exists(bsp_path):\n    print(f\"Error: Ephemeris file '{bsp_path}' not found.\")\n    print(\"Please download a .bsp kernel (e.g., de421.bsp) and set the\")\n    print(\"JPLEPHEM_BSP_PATH environment variable, or place the file in the current directory.\")\n    print(\"Skipping ephemeris calculation.\")\nelse:\n    try:\n        ephemeris = Ephemeris(bsp_path)\n        print(f\"Successfully loaded ephemeris from: {bsp_path}\")\n\n        # Calculate position of Earth-Moon Barycenter (body 3) relative to\n        # Solar System Barycenter (body 0) on January 1, 2000.\n        target_date = datetime(2000, 1, 1, 12, 0, 0) # Noon UTC\n        jd = convert_datetime_to_jd(target_date)\n\n        # The 'observer' is the body from which the 'target' is observed.\n        # Here, observer=0 (Solar System Barycenter), target=3 (Earth-Moon Barycenter).\n        # The result is a 3-element NumPy array: [x, y, z] in AU.\n        position_vector = ephemeris.position(3, 0, jd)\n\n        print(f\"\\nDate: {target_date.isoformat()}\")\n        print(f\"Julian Date: {jd}\")\n        print(f\"Position of Earth-Moon Barycenter relative to SSB (AU):\")\n        print(f\"  x={position_vector[0]:.6f}, y={position_vector[1]:.6f}, z={position_vector[2]:.6f}\")\n\n        # Example with velocity:\n        velocity_vector = ephemeris.velocity(3, 0, jd)\n        print(f\"Velocity of Earth-Moon Barycenter relative to SSB (AU/day):\")\n        print(f\"  vx={velocity_vector[0]:.6f}, vy={velocity_vector[1]:.6f}, vz={velocity_vector[2]:.6f}\")\n\n    except Exception as e:\n        print(f\"An error occurred while using the ephemeris: {e}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Download required `.bsp` files (e.g., `de421.bsp`, `de440.bsp`) from `ftp://ssd.jpl.nasa.gov/pub/eph/planets/bsp/` or `https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/` and provide their path to `jplephem.ephem.Ephemeris` or `jplephem.spk.SPK`.","message":"jplephem requires external JPL ephemeris (.bsp) data files, which are often large (hundreds of MBs) and are NOT bundled with the library. These files must be downloaded separately from JPL's FTP server or NASA's PDS.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use `jplephem.jpllib.convert_datetime_to_jd()` to safely convert Python `datetime` objects to the required Julian Date format for ephemeris calculations.","message":"jplephem internally operates with Julian Dates (JD). While a helper exists for `datetime` conversion, users should be aware of this time system.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always check the documentation for the specific method (e.g., `position()`, `velocity()`) to confirm the units of the returned array. Perform explicit unit conversions if other units are required for your application.","message":"Output positions are typically in Astronomical Units (AU) and velocities in AU per day by default. Be mindful of these units when interpreting results.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}