Developers can check out this full project from GitHub:
https://github.com/brandon-rhodes/python-sgp4
To run its unit tests, install Python2, Python3, and the ``tox``
testing tool. The tests runing in Python2 will exercise the fallback
pure-Python version of the routines, while Python3 exercises the fast
new C++ accelerated code::
cd python-sgp4
tox
Legacy API
----------
Before this library pivoted to wrapping Vallado's official C++ code and
was operating in pure Python only, it had a slightly quirkier API, which
is still supported for compatibility with older clients. You can learn
about it by reading the documentation from version 1.4 or earlier:
https://pypi.org/project/sgp4/1.4/
Changelog
---------
2026-07-03 — 2.27
* Moved the project documentation out of the ``__init__.py`` docstring
and into the source code README file, which should hopefully make the
documentation reappear on the project’s PyPI page.
2026-06-26 — 2.26
* The C++ module now limits itself to calling the Python Limited API and
can therefore link against the Python Stable ABI, producing a binary
wheel that’s compatible with multiple versions of Python. Hopefully
this means that new Python releases no longer require sgp4 to be
immediately re-released to support them.
2025-08-04 — 2.25
* Added a ``gravconst`` parameter to the ``omm.initialize()`` routine
for folks using gravity models other than ``WGS72``, or who at least
want to make that choice explicit in their code.
* Added a ``revnum`` attribute to satellites built with ``sgp4init()``
(it defaults to the dummy value of zero), so they can be passed to
``export_tle()`` without raising an exception.
2024-02-15 — 2.24
* The documentation now specifies the acceptable range for orbital
element angles like inclination and mean anomaly, and a new function
``check_satrec(sat)`` will tell the caller if any of the angles are
out of bounds.
* The documentation now gives an example of loading elements from JSON.
* Tweaked the fallback Python code to accept TLE lines without a final
checksum character in the 69th column, to match the C++ code.
2023-10-01 — 2.23
* Tweaked tests to resolve breakage introduced by Python3.12.
2023-04-27 — 2.22
* Added a ``satnum_str`` attribute, exposing the fact that the C++ now
stores the satellite number as a string; and check that ``satnum`` is
never greater than 339999.
* Fixed the units of the ``nddot`` attribute when the value is loaded
from an OMM record. (Since the TLE computation itself ignores this
attribute, this did not affect any satellite positions.)
* Enhanced the fallback Python version of ``twoline2rv()`` to verify
that TLE lines are ASCII, and added documentation using it to
double-check TLEs that might suffer from non-ASCII characters.
* If the user doesn’t set a satellite’s ``classification``, it now
defaults to ``'U'`` for ‘unclassified’.
2022-04-06 — 2.21
* Added ``dump_satrec()`` to the ``sgp4.conveniences`` module.
* Fixed the ``Satrec`` attribute ``.error``, which was previously
building a nonsense integer from the wrong data in memory.
* Removed ``.whichconst`` from Python ``Satrec``, to help users avoid
writing code that will break when the C++ extension is available.
2021-07-01 — 2.20
* Taught ``sgp4init()`` to round both ``epochdays`` and ``jdsatepochF``
to the same 8 decimal places used for the date fraction in a TLE, if
the user-supplied ``epoch`` itself has 8 or fewer digits behind the
decimal point. This should make it easier to build satellites that
round-trip to TLE format with perfect accuracy.
* Fixed how ``export_tle()`` formats the BSTAR field when its value, if
written in scientific notation, has a positive exponent.
* Fixed the ``epochyr`` assigned by ``sgp4init()`` so years before 2000
have two digits instead of three (for example, so that 1980 produces
an ``epochyr`` of 80 instead of 980).
2021-04-22 — 2.19
* Extended the documentation on the Python Package Index and in the
module docstring so it lists every ``Satrec`` attribute that this
library exposes; even the more obscure ones might be useful to folks
working to analyze satellite orbits.
2021-03-08 — 2.18
* If a TLE satellite number lacks the required 5 digits,
``twoline2rv()`` now gives the underlying C++ library a little help so
it can still parse the classification and international designator
correctly.
* The ``Satrec`` attributes ``jdsatepoch``, ``jdsatepochF``,
``epochyr``, and ``epochdays`` are now writeable, so users can adjust
their values manually — which should make up for the fact that the
``sgp4init()`` method can’t set them with full floating point
precision.
| 2021-02-17 — 2.17 — Fixed where in the output array the ``sgp4_array()`` method writes NaN values when an SGP4 propagation fails.
| 2021-02-12 — 2.16 — Fixed ``days2mdhms()`` rounding to always match TLE epoch.
| 2021-01-08 — 2.15 — Fixed parsing of the ``satnum`` TLE field in the Python fallback code, when the field has a leading space; added OMM export routine.
| 2020-12-16 — 2.14 — New data formats: added OMM message support for both XML and CSV, and added support for the new Alpha-5 extension to TLE files.
| 2020-10-14 — 2.13 — Enhanced ``sgp4init()`` with custom code that also sets the ``epochdays`` and ``epochyr`` satellite attributes.
| 2020-05-28 — 2.12 — Moved the decision of whether to set the locale during ``twoline2rv()`` from import time to runtime, for users who change locales after their application is up and running.
| 2020-05-24 — 2.11 — Fixed a regression in how dates are split into hours, minutes, and seconds that would sometimes produce a time whose second=60, crashing the pure-Python version of the library.
| 2020-05-22 — 2.10 — Switch the locale temporarily to ``C`` during the C++ accelerated ``twoline2rv()``, since it does not protect its ``sscanf()`` calls from locales that, like German, expect comma decimal points instead of the period decimal points always used in a TLE.
| 2020-05-21 — 2.9 — Added ``sat_epoch_datetime()``, expanded documentation around converting a satellite epoch to a date and time, and started rounding the epoch to exactly the digits provided in the TLE; and removed the ``Satrec.epoch`` attribute from Python fallback code to better match the C++ version.
| 2020-05-07 — 2.8 — New function ``jday_datetime()`` is now available in the ``sgp4.conveniences`` module, thanks to Egemen Imre.
| 2020-04-24 — 2.7 — New method ``sgp4init()`` (thank you, Chris Lewicki!) is available.
| 2020-04-20 — 2.6 — New routine ``export_tle()`` (thank you, Egemen Imre!) is available. Improved how the accelerated C++ backend parses the ``intldesg`` string and the ``revnum`` integer.
| 2020-03-22 — 2.5 — Gave the new accelerated ``twoline2rv()`` an optional argument that lets the user choose a non-standard set of gravity constants.
| 2020-02-25 — 2.4 — Improved the ``jday()`` docstring; made the old legacy Python resilient if the day of the month is out-of-range (past the end of the month) in a TLE; and Mark Rutten fixed the C++ so it compiles on Windows!
| 2020-02-04 — 2.3 — Removed experimental code that caused performance problems for users with Numba installed.
| 2020-02-02 — 2.2 — A second release on Palindrome Day: fix the Satrec ``.epochyr`` attribute so it behaves the same way in Python as it does in the official C library, where it is only the last 2 digits of the year; and make ``.no`` available in the Python fallback case as well.
| 2020-02-02 — 2.1 — Add vectorized array method to Satrec object; add ``.no`` attribute to new Satrec object to support old code that has not migrated to the new name ``.no_kozai``; gave Python wrapper classes ``__slots__`` to avoid the expense of a per-object attribute dictionary.
| 2020-01-30 — 2.0 — Rewrite API to use genuine Vallado C++ code on those systems where it can be compiled; add accelerated vectorized array interface; make ``gstime()`` a public function; clarify format error message.
| 2015-01-15 — 1.4 — Display detailed help when TLE input does not match format.
| 2014-06-26 — 1.3 — Return ``(NaN,NaN,NaN)`` vectors on error and set ``.error_message``
| 2013-11-29 — 1.2 — Made ``epochyr`` 4 digits; add ``datetime`` for ``.epoch``
| 2012-11-22 — 1.1 — Python3 compatibility; more documentation
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
