{"id":5057,"library":"sgp4","title":"SGP4 Satellite Orbit Propagator","description":"The `sgp4` Python library provides a highly accurate implementation of the SGP4 and SDP4 orbital propagation algorithms, as described in the 2020 revision of the Spacetrack Report #3. It allows users to track Earth satellites given their Two-Line Element (TLE) data, predicting their position and velocity at specific times. The library is actively maintained, with version 2.25 being the latest, and typically sees several releases per year addressing minor bugs and precision improvements.","status":"active","version":"2.25","language":"en","source_language":"en","source_url":"https://github.com/brandon-rhodes/python-sgp4","tags":["satellite","orbital mechanics","SGP4","TLE","aerospace","astronomy","spacecraft"],"install":[{"cmd":"pip install sgp4","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"Main class for satellite representation and propagation.","symbol":"Satrec","correct":"from sgp4.api import Satrec"},{"note":"WGS-72 Earth model, often used in conjunction with SGP4.","symbol":"WGS72","correct":"from sgp4.api import WGS72"},{"note":"Utility function to convert Python datetime objects to Julian date (jd, fr) pair for SGP4. Recommended over manual conversion or direct `Satrec.jday()` for `datetime` objects.","symbol":"jday_from_datetime","correct":"from sgp4.api import jday_from_datetime"}],"quickstart":{"code":"from datetime import datetime, timezone\nfrom sgp4.api import Satrec\n\n# Example TLE for NOAA 15 (valid for a specific epoch)\n# Use actual current TLE data for real-world applications\ntle_line1 = '1 25338U 98030A   23098.50000000  .00000000  00000-0  57606-2 0  9994'\ntle_line2 = '2 25338  98.7402  65.3400 0001000  90.0000  270.0000 14.28000000000000'\n\n# Parse the TLE data into a Satrec object\nsatellite = Satrec.twoline2_parse(tle_line1, tle_line2)\n\n# Define the time for propagation (example: April 8, 2023, 12:00:00 UTC)\n# SGP4 expects naive UTC datetimes or Julian dates.\nprop_time = datetime(2023, 4, 8, 12, 0, 0, tzinfo=timezone.utc).replace(tzinfo=None)\n\n# Propagate the satellite to the specified time\n# The sgp4 method returns (error_code, position_km, velocity_km_s)\ne, r, v = satellite.sgp4(\n    prop_time.year, prop_time.month, prop_time.day,\n    prop_time.hour, prop_time.minute, prop_time.second + prop_time.microsecond / 1_000_000\n)\n\nif e == 0:\n    print(f\"Satellite ID: {satellite.satnum}\")\n    print(f\"Propagation time: {prop_time} UTC\")\n    print(f\"Position (km, ECI): {r}\")\n    print(f\"Velocity (km/s, ECI): {v}\")\nelse:\n    print(f\"SGP4 error code: {e}. Check TLE validity or propagation time range.\")","lang":"python","description":"This quickstart demonstrates how to parse Two-Line Element (TLE) data for a satellite, define a specific propagation time in UTC, and then use the `sgp4` method of the `Satrec` object to calculate the satellite's Earth-Centered Inertial (ECI) position and velocity. The output units are kilometers and kilometers per second."},"warnings":[{"fix":"Ensure all `datetime` objects passed to `sgp4` methods are converted to naive UTC. Use `dt.astimezone(timezone.utc).replace(tzinfo=None)` for timezone-aware datetimes.","message":"`sgp4` expects naive UTC `datetime` objects or Julian dates. Passing timezone-aware `datetime` objects or naive `datetime` objects in a non-UTC timezone can lead to incorrect calculations or errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Multiply position components by 1000 to get meters, and velocity components by 1000 to get meters/second, if required.","message":"The position and velocity outputs from `satellite.sgp4()` are always in kilometers (km) and kilometers per second (km/s) respectively. Users expecting meters or other units must perform explicit conversions.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Validate TLE input strings for correct format and length before parsing. Use a reliable source for TLE data.","message":"The `Satrec.twoline2_parse` method requires TLE strings to adhere strictly to the NORAD two-line element set format (69 characters per line). Malformed TLEs (e.g., incorrect length, invalid characters) will result in `ValueError` or `IndexError`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For converting `datetime` objects to Julian dates, use `sgp4.api.jday_from_datetime()` which returns the correct `(jd, fr)` pair. If directly calling `Satrec.jday()`, update code to expect `(jd, fr)` instead of a single float.","message":"In `sgp4` version 1.10, the direct return type of `Satrec.jday()` changed from a single Julian date float to a tuple of two floats (Julian date integer part, Julian date fractional part). While the `sgp4()` propagation method handles this internally, direct access to `Satrec.jday` from code written for versions prior to 1.10 will break if not updated.","severity":"breaking","affected_versions":"Versions 1.10 and later (vs. pre-1.10)"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}