Skyfield: Home • Table of Contents • API Reference
Skyfield has only a single binary dependency, the NumPy vector library, and is designed to install cleanly with a single invocation of the standard Python package tool:
pip install skyfield
This should install Skyfield, NumPy,
and the small collection of pure-Python astronomy libraries
that Skyfield depends on.
If you lack
pip and need to install each dependency by hand,
setup.py file for the full list.
If trying to install Skyfield gives you errors about NumPy, there are several other ways to get NumPy installed:
You can download and run an official NumPy installer.
You can try to get the plain
pip-powered install working
by giving your system a functioning C compiler
that matches the compiler used to build Python.
On Windows with Python 2.7, try installing the free
Visual Studio Express 2008.
Mac users should install the “Xcode Command Line Tools”
pip the superpower of being able to build and install
binary Python dependencies like NumPy.
Read the Changelog below to learn about recent fixes, changes,
and improvements to Skyfield.
You can protect your project from any abrupt API changes
by pinning a specific version of Skyfield
setup.py or install instructions:
By preventing Skyfield from getting accidentally upgraded until you are ready to advance the version number yourself, you can avoid being blindsided by improvements that take place between now and the eventual 1.0 version. If you find any problems or would like to suggest an improvement, simply create an issue on the project’s GitHub page:
If Skyfield has proven useful in your research, the project welcomes your citation to bring it to the attention of other academics who might benefit from it. Here is Skyfield’s DOI:
Loaderpointed at a Windows directory for which Python’s
os.makedirs()function returned a spurious error. #283
reverse_terra()routine can now be given an
iterations=0argument if the caller wants geocentric latitude and longitude.
load.timescale(builtin=True)to use time scale files that Skyfield carries internally, instead of downloading them. Note that the time scale files distributed with any given version of Skyfield will gradually fall out of date.
from_dataframe()now correctly pulls stellar parallax data from the dataframe if available. #266
find_discrete()was generating empty arrays of search dates, upsetting the astronomy code, if the start and end dates were very close together. #240
deltat.preds, whose change in format caused Skyfield to start throwing an exception for new users. #236
cirs_radec()have been contributed which provide support for rotating a position into the Celestial Intermediate Reference System (CIRS). #192
load()routine have been fixed. #193 #194
tle()now accept not just URLs but also plain local file paths; they correctly re-download a remote file if “reload=True” is specified; and they allow specifying a different local “filename=” than the one at the end of the URL.
subpoint()method now normalizes the longitude values it returns into the range −180° to 180° #182 and returns an actual elevation instead of zero. #185
ITRF_position_velocity_error()method that returns raw ITRF coordinates for users interested in them. #85
subpoint()method that computes the latitude and longitude of the point beneath that body.
Timescaletime constructor methods now accept arrays.
deltat.preds, since the file has gone out of date at the USNO site.
Starto be initialized with a tuple that breaks units into minutes and seconds (broke in version 1.2).
~now means “your home directory”.
EarthSatellite()instead of having it trying to load one itself.
topos()method in favor of vector addition.
satellite()method in favor of vector addition.
geometry_of()method in favor of vector subtraction.
observe()method of an observer on the Earth’s surface now correctly accounts for the way that the Earth’s gravity will deflect the apparent position of objects that are not exactly overhead, bringing Skyfield’s agreement with the Naval Observatory’s NOVAS library to within half a milliarcsecond.
tt_calendar()method no longer raises a
TypeErrorwhen its value is an array.
Timearray now produces a more compact string that only mentions the start and end of the time period.
api.load()call no longer attempts to animate a progress bar if the user is running it under IDLE, which would try to accumulate the updates as a single long line that eventually hangs the window.
ICRF.separation_from()computes the angular separation between two positions.
Timeobjects and other unrelated objects so that it no longer raises an exception.
Timescale object with methods
tdb() for building time objects, along with a
load.timescale() method for building a new
load method downloads ΔT and leap second data from official data
sources and makes sure the files are kept up to date. This replaces
all former techniques for building and specifying dates and times.
Time and switched from
as the typical variable used for time in the documentation.
Deprecated timescale keyword arguments like
utc=(…) for both the
Time constructor and also for all methods that take time as
an argument, including
Users who want to specify a target directory when downloading a file will now create their own loader object, instead of having to specify a special keyword argument for every download:
load = api.Loader('~/ephemeris-files') load('de421.bsp')
Users can now supply a target
directory when downloading a file:
Fix: removed inadvertent dependency on the Pandas library.
load() was raising a
PermissionError on Windows after a
successful download when it tried to rename the new file.
delta_tif the user does not supply their own
delta_t=keyword when specifying a date. This should make altitude and azimuth angles much more precise.
Skyfield has dropped the 16-megabyte JPL ephemeris DE421 as an install
dependency, since users might choose another ephemeris, or might not
need one at all. You now ask for a SPICE ephemeris to be downloaded
at runtime with a call like
planets = load('de421.bsp').
Planets are no longer offered as magic attributes, but are looked up
through the square bracket operator. So instead of typing
planets.mars you should now type
planets['mars']. You can run
print(planets) to learn which bodies an ephemeris supports.
Per IAU 2012 Resolution B2, Skyfield now uses lowercase au for the
astronomical unit, and defines it as exactly 149 597 870 700 meters.
While this API change is awkward for existing users, I wanted to make
the change while Skyfield is still pre-1.0. If this breaks a program
that you already have running, please remember that a quick
skyfield==0.4 will get you up and running again until
you have time to edit your code and turn
utc_datetime()methods have been changed to return only a
datetimeobject. If you also need a leap second flag returned, call the new methods
a.hoursare now attributes instead of method calls.