skyfield

library1.55pypypi✓ verified 22d ago

Skyfield is an elegant Python library for high-precision astronomy calculations. It allows users to compute the positions of planets, satellites, stars, and other celestial bodies from any point on Earth or in space, at any moment in time. It leverages JPL ephemeris data to achieve high accuracy. It's actively maintained with regular releases, often several per year, reflecting ongoing development and bug fixes.

data

pip install skyfield

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SKYFIELD

skyfield

datapythonv1.55

Install

4.3s avg

Import

433ms

Disk

93MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.55 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.448s · 92.6MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 4.3s · import 0.418s · 89MB

93MB installed

● package 93MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

load

✓ from skyfield.api import load

Topos

✓ from skyfield.api import Topos

✓ from skyfield.api import load; ts = load.timescale()

✗ from skyfield.timelib import Timescale; ts = Timescale()

Directly instantiating `Timescale` requires manually providing paths to leap second files. `load.timescale()` handles this automatically.

This quickstart calculates the astrometric position of Mars as seen from Greenwich, UK, on Christmas Day 2024. It demonstrates loading ephemeris data, defining an observer's location, specifying a time, and performing an observation to retrieve celestial coordinates.

from skyfield.api import load, Topos # Load the ephemeris data; downloads if not present. eph = load('de421.bsp') # Get the timescale object for precise time calculations. ts = load.timescale() # Define an observer's location (e.g., Greenwich, UK) greenwich = Topos(latitude_degrees=51.478, longitude_degrees=0.0) # Define a specific moment in time (UTC) t = ts.utc(2024, 12, 25, 12, 0, 0) # Christmas Day 2024, Noon UTC # Observe Mars from Earth, as seen from Greenwich astrometric = greenwich.at(t).observe(eph['mars']) # Get the astrometric position (Right Ascension, Declination, Distance) ra, dec, distance = astrometric.radec() print(f"Time (UTC): {t.utc_datetime()}") print(f"Mars Right Ascension: {ra}") print(f"Mars Declination: {dec}") print(f"Distance to Mars: {distance}")

Debug

Known issues

gotchaSkyfield requires large ephemeris data files (e.g., `de421.bsp`). These files are downloaded on first use when `load('filename.bsp')` is called. This requires an active internet connection and write permissions to the data directory (typically `~/.skyfield/data`). In environments without internet or write access, this will fail.

fix

Ensure internet connectivity and proper file permissions. For constrained environments, pre-download the necessary `.bsp` files and specify their path: `eph = load('/path/to/my_data_folder/de421.bsp')`.

affects: All versions

gotchaSince Skyfield 1.36, the `radec()` and `altaz()` methods on observation objects return a dedicated object (e.g., `_Astrometric`) rather than a simple 3-tuple. While Python's sequence unpacking (`ra, dec, distance = obs.radec()`) still works, directly accessing values by index (e.g., `obs.radec()[0]`) will fail, as the returned object is not a `tuple`.

fix

Access the attributes directly from the returned object (e.g., `astrometric = obs.radec(); ra = astrometric.ra`) or continue using sequence unpacking if only the main three values are needed. Avoid direct index access on the returned object.

affects: 1.36 and later

gotchaSkyfield uses its own precise `Time` objects, which are crucial for accurate astronomical calculations and handle leap seconds, TAI, TT, and UTC correctly. Mixing these with naive Python `datetime` objects or incorrectly converting timezone-aware `datetime` objects can lead to subtle but significant errors due to differences in time scales, daylight saving time, or floating-point precision.

fix

Always construct `skyfield.timelib.Time` objects using methods from the `timescale` object (e.g., `ts.utc(year, month, day)`, `ts.utcfromtimestamp()`). If converting from a `datetime` object, use `ts.utcfromdatetime(my_datetime_obj)` and ensure `my_datetime_obj` is timezone-aware and in UTC if possible.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'skyfield'

The Skyfield library is not installed in your current Python environment.

fix

pip install skyfield

AttributeError: 'datetime.datetime' object has no attribute 'tt'

You are passing a standard Python `datetime.datetime` object to a Skyfield function that expects a Skyfield `Time` object, which has specific attributes like `tt` (Terrestrial Time).

fix

Convert your `datetime` object to a Skyfield `Time` object using `ts.from_datetime()` or by manually passing its components to `ts.utc()` or `ts.ut1()`.

```python
from skyfield.api import load
from datetime import datetime

ts = load.timescale()
dt_obj = datetime.utcnow() # Your datetime object
skyfield_time = ts.from_datetime(dt_obj) # Correct way
# or: skyfield_time = ts.utc(dt_obj.year, dt_obj.month, dt_obj.day, dt_obj.hour, dt_obj.minute, dt_obj.second)
```

KeyError: 'mars'

The ephemeris file you loaded (e.g., `de405s.bsp`) does not contain data for the requested celestial body (e.g., Mars), as smaller ephemeris files often only include data for the Sun, Moon, and Earth.

fix

Load a larger ephemeris file that includes the major planets, such as `de421.bsp`, `de422.bsp`, or `de430t.bsp`.

```python
from skyfield.api import load

planets = load('de421.bsp') # Load a larger ephemeris file
mars = planets['mars']
```

ValueError: TLE line 1 is wrong length (expected 69 chars): '...'

One of the provided TLE (Two-Line Elements) strings is malformed, specifically having an incorrect number of characters for the first line. TLEs require a strict fixed-width format of 69 characters per line.

fix

Ensure that both TLE lines are exactly 69 characters long, including any trailing spaces, and that they conform precisely to the TLE format. Verify the source of your TLE data for correctness.

```python
from skyfield.api import EarthSatellite, load

ts = load.timescale()

# Correct TLE example (both lines are 69 characters)
line1 = '1 25544U 98067A   23348.69460010  .00000880  00000-0  29528-4 0  9997'
line2 = '2 25544  51.6416 118.9950 0005917 217.4338 249.9547 15.49884521404169'
satellite = EarthSatellite(line1, line2, 'ISS (ZARYA)', ts)
```

FileNotFoundError: [Errno 2] No such file or directory: 'de421.bsp'

The required ephemeris data file (e.g., 'de421.bsp') was not found in the expected location, and Skyfield could not download it automatically.

fix

Ensure an active internet connection for Skyfield to download the ephemeris, or provide the correct path to a pre-downloaded file. The `load()` function handles downloading by default. Example: `from skyfield.api import load; planets = load('de421.bsp')`

Upgrade

Version history

1.55latest on PyPI · released Aug 7, 2026

Audit

Dependencies

numpyrequiredRequired for high-performance numerical computations.

jplephemrequiredRequired for parsing and using JPL ephemeris data files.

sgp4requiredRequired for satellite orbital calculations (Two-Line Elements).

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttp://github.com/brandon-rhodes/python-skyfield ↗

packagehttps://pypi.org/project/skyfield/ ↗

homepagehttps://rhodesmill.org/skyfield/ ↗