{"id":5483,"library":"skyfield","title":"Skyfield","description":"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.","status":"active","version":"1.54","language":"en","source_language":"en","source_url":"https://github.com/brandon-rhodes/python-skyfield/","tags":["astronomy","celestial mechanics","ephemeris","space","physics","satellite"],"install":[{"cmd":"pip install skyfield","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for high-performance numerical computations.","package":"numpy"},{"reason":"Required for parsing and using JPL ephemeris data files.","package":"jplephem"},{"reason":"Required for satellite orbital calculations (Two-Line Elements).","package":"sgp4"}],"imports":[{"symbol":"load","correct":"from skyfield.api import load"},{"symbol":"Topos","correct":"from skyfield.api import Topos"},{"note":"Directly instantiating `Timescale` requires manually providing paths to leap second files. `load.timescale()` handles this automatically.","wrong":"from skyfield.timelib import Timescale; ts = Timescale()","symbol":"ts","correct":"from skyfield.api import load; ts = load.timescale()"}],"quickstart":{"code":"from skyfield.api import load, Topos\n\n# Load the ephemeris data; downloads if not present.\neph = load('de421.bsp')\n\n# Get the timescale object for precise time calculations.\nts = load.timescale()\n\n# Define an observer's location (e.g., Greenwich, UK)\ngreenwich = Topos(latitude_degrees=51.478, longitude_degrees=0.0)\n\n# Define a specific moment in time (UTC)\nt = ts.utc(2024, 12, 25, 12, 0, 0) # Christmas Day 2024, Noon UTC\n\n# Observe Mars from Earth, as seen from Greenwich\nastrometric = greenwich.at(t).observe(eph['mars'])\n\n# Get the astrometric position (Right Ascension, Declination, Distance)\nra, dec, distance = astrometric.radec()\n\nprint(f\"Time (UTC): {t.utc_datetime()}\")\nprint(f\"Mars Right Ascension: {ra}\")\nprint(f\"Mars Declination: {dec}\")\nprint(f\"Distance to Mars: {distance}\")","lang":"python","description":"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."},"warnings":[{"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')`.","message":"Skyfield 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Since 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`.","severity":"gotcha","affected_versions":"1.36 and later"},{"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.","message":"Skyfield 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}