Install & Compatibility
Where this runs
tested against v2.27 · 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.002s · 18.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.000s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Satrec
✓ from sgp4.api import Satrec
Main class for satellite representation and propagation.
WGS72
✓ from sgp4.api import WGS72
WGS-72 Earth model, often used in conjunction with SGP4.
jday_from_datetime
✓ from sgp4.api import jday_from_datetime
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.
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.
from datetime import datetime, timezone
from sgp4.api import Satrec
# Example TLE for NOAA 15 (valid for a specific epoch)
# Use actual current TLE data for real-world applications
tle_line1 = '1 25338U 98030A 23098.50000000 .00000000 00000-0 57606-2 0 9994'
tle_line2 = '2 25338 98.7402 65.3400 0001000 90.0000 270.0000 14.28000000000000'
# Parse the TLE data into a Satrec object
satellite = Satrec.twoline2_parse(tle_line1, tle_line2)
# Define the time for propagation (example: April 8, 2023, 12:00:00 UTC)
# SGP4 expects naive UTC datetimes or Julian dates.
prop_time = datetime(2023, 4, 8, 12, 0, 0, tzinfo=timezone.utc).replace(tzinfo=None)
# Propagate the satellite to the specified time
# The sgp4 method returns (error_code, position_km, velocity_km_s)
e, r, v = satellite.sgp4(
prop_time.year, prop_time.month, prop_time.day,
prop_time.hour, prop_time.minute, prop_time.second + prop_time.microsecond / 1_000_000
)
if e == 0:
print(f"Satellite ID: {satellite.satnum}")
print(f"Propagation time: {prop_time} UTC")
print(f"Position (km, ECI): {r}")
print(f"Velocity (km/s, ECI): {v}")
else:
print(f"SGP4 error code: {e}. Check TLE validity or propagation time range.")
Debug
Known issues
gotcha`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.fixEnsure all `datetime` objects passed to `sgp4` methods are converted to naive UTC. Use `dt.astimezone(timezone.utc).replace(tzinfo=None)` for timezone-aware datetimes.
affects: All versions
gotchaThe 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.fixMultiply position components by 1000 to get meters, and velocity components by 1000 to get meters/second, if required.
affects: All versions
gotchaThe `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`.fixValidate TLE input strings for correct format and length before parsing. Use a reliable source for TLE data.
affects: All versions
breakingIn `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.fixFor 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.
affects: Versions 1.10 and later (vs. pre-1.10)
Upgrade
Version history
2.27latest on PyPI · released Jul 3, 2026
Audit
Dependencies
No dependency data recorded yet.