Installation

weewx-skyfield manual · weewx-skyfield on GitHub · Report an issue

weewx-skyfield requires Python 3.9 or later, WeeWX 5.2 or later, and the Skyfield (1.47 or later; 1.49 for satellites) and NumPy libraries. PyEphem is not required. Translated body, constellation and meteor shower names need WeeWX 5.3 or later — see Translations.

Installing the extension

  1. Install the prerequisite Skyfield package (1.49 or later).

    For a pip/venv WeeWX install, activate the virtual environment (actual syntax varies by type of WeeWX install) and install with pip:

    source /home/weewx/weewx-venv/bin/activate
pip install 'skyfield>=1.49'

    For a Debian package install:

    sudo apt install python3-skyfield

    apt show python3-skyfield reports the version; Debian 12 “bookworm” ships 1.45, which is too old — use pip in that case. On an older Skyfield the install stops and says why; if Skyfield is downgraded afterwards, the extension logs an error and leaves the built-in almanac in place.

  2. Download the latest release, weewx-skyfield.zip, from the weewx-skyfield GitHub repository. It is a large download: the bundled DE421 ephemeris (17 MB) and the complete Hipparcos star catalog (15 MB gzipped) are most of it, with the documentation’s screenshots accounting for nearly all the rest.

  3. Install the extension.

    On a pip install weectl lives in the virtual environment, so activate it first (yours may sit elsewhere; ~/weewx-venv is the usual place):

    source ~/weewx-venv/bin/activate
weectl extension install weewx-skyfield.zip

    On a Debian or Red Hat package install there is no environment to activate and weectl is already on the path:

    weectl extension install weewx-skyfield.zip

    No sudo: that install put your account in the weewx group, which owns the files. If you installed WeeWX in this same login session, log out and back in first so the group membership takes effect.

    The install pauses here to fetch the first satellite and comet orbital elements, so the tags work from the first report cycle rather than the next refresh. It says what it is downloading before each one — the comet file is the slow one — and elements the station already has, still current, are not fetched again, so a reinstall or an upgrade over a running station usually goes straight through. A download that fails is not fatal, but it stops the asking, as CelesTrak’s usage policy requires: the satellites after it are not asked for, and weewxd asks again when it starts. A message naming a satellite and its NORAD number is the one exception — CelesTrak has no current elements for it, so check that number in [[Satellites]]; the rest are still fetched.

  4. Restart WeeWX.

  5. Confirm it took. The extension announces itself in the log; this is the line that says your reports are now using Skyfield:

    Skyfield almanac registered; reports will use Skyfield for almanac computations.

    If that line is absent, one of the startup messages says why — an older WeeWX, an older Skyfield, or enable = false.

Reports generated from then on (e.g., the Seasons skin’s Celestial page) use Skyfield almanac values. No skin changes are needed: the extension answers the same $almanac tags as the built-in almanac. The Sky page appears alongside your existing reports at <HTML_ROOT>/skyfield/index.html after the first report cycle.

Upgrading over a running WeeWX is safe: the ephemeris is read fully into memory at startup, so replacing the extension’s files cannot disturb the running almanac; the new files take effect on the restart that follows the install.

Upgrading Skyfield

Skyfield 1.47 is the minimum. Satellites need 1.49 or later: their elements arrive in the OMM format, which earlier Skyfield cannot read. The extension is developed and its test suite run against the current Skyfield release — 1.55 as of August 2026 — and upgrading to it is recommended. To see what you have:

/home/weewx/weewx-venv/bin/python -c 'import skyfield; print(skyfield.__version__)'

For a pip/venv WeeWX install, upgrade with the virtual environment’s pip, then restart WeeWX:

source /home/weewx/weewx-venv/bin/activate
pip install --upgrade skyfield

For a Debian package install, apt serves the distribution’s version, which lags the Skyfield release (Debian 12 ships 1.45, well below the minimum). Where the packaged version is too old, install with pip as described above instead.

Configuration

The installer adds a [Skyfield] section to weewx.conf and a [[SkyfieldReport]] stanza under [StdReport]. Both, and every option in them, are documented on one page: Configuration.

The two sections below cover what the satellite and comet options do — where the orbital elements come from, how often they refresh, and how to run without any network access at all.

Satellites

Satellite positions are computed (by Skyfield’s SGP4 implementation) from published orbital elements, which age quickly — a reboost or maneuver makes week-old elements minutes wrong — so, unlike the ephemeris and the star catalog, they cannot ship in a release. They are fetched from CelesTrak: once at install time — skipped when the station already has elements less than three hours old — then by weewxd, which checks for missing or stale elements at every startup — a satellite just added to the configuration is live seconds after the restart — and refreshes about every three hours thereafter, on a worker thread that never blocks reports. A failed fetch keeps the old file and is never retried quickly. CelesTrak’s usage policy asks software to stop querying at any answer but a good one and report it to a person, and an address that keeps asking through errors ends up in its firewall, so:

  • a 404 saying “No GP data found” is a catalog number CelesTrak does not carry — a typo, or an object that has decayed. That satellite is not asked for again until weewxd restarts, an error names the number to check, and the other satellites are still fetched. Any other 404 means an outdated URL, and is treated as below;
  • anything else — any other status (a 403 or 429 for an address asking too often, a 5xx for a server under load, a 301 for an outdated URL, which is never followed), an answer that is not elements, or no answer at all — stops the round: no satellite is asked for again until the next one, three hours on, and one error carries the answer’s own words.

Restarting weewxd asks again at once. Each satellite’s elements live in their own file, wxskyfield_sat_<norad>.csv, in a wxskyfield directory beside the station’s SQLite database (under SQLITE_ROOT), and survive restarts. The file is CelesTrak’s answer exactly as it came: the elements in the OMM format, as CSV — a header line and one row. Releases before 2.10 fetched TLEs (two-line element sets) instead, but a TLE has room for only five digits of catalog number, and the catalog passed 99999 in July 2026. After an upgrade each satellite’s old .tle file serves until its elements are next due, when the fetch writes the .csv and deletes the .tle, so the upgrade adds no request to CelesTrak. Elements whose epoch is more than seven days older than the almanac’s time are not used: every tag for that satellite reads “N/A” rather than reporting confidently wrong pass times, a warning is logged (once at the crossing, not per tag), and the always-live diagnostic tags $almanac.iss.elements_epoch and $almanac.iss.elements_age say why.

This is one of the extension’s two network accesses — comet elements, below, are the other — and it has a switch of its own. Set satellite_downloads = false in the [Skyfield] section — on a fresh install the line is already there, commented out, so uncomment it and change the value — and no satellite fetch is ever made; with comet_downloads = false beside it the extension fetches nothing at all, ever — the behavior every release before 2.0 had unconditionally. In that mode [[Satellites]] still works if you maintain the element files yourself: an air-gapped station can copy files in by any means it likes, in either form. wxskyfield_sat_<norad>.csv is OMM as CSV — CelesTrak’s FORMAT=CSV answer, or Space-Track’s OMM CSV, whose extra columns are ignored. wxskyfield_sat_<norad>.tle is a TLE — an optional name line and the two element lines, the catalog number written plain or, past 99999, in the Alpha-5 form (E8493 is 148493). When both files are there the one with the later epoch is used, and with downloads off the extension never deletes either. The seven-day age cutoff applies all the same, because stale elements cannot predict passes no matter how they arrived. With no [[Satellites]] configured, likewise, nothing is ever fetched. The fetch identifies itself as weewx-skyfield/<version> with the project URL, and weectl extension uninstall does not remove the cached element files — delete the wxskyfield directory yourself if you want them gone.

Choosing satellites. Any satellite CelesTrak carries can be added by NORAD number (satellite catalog search), up to 339999: SGP4, which computes the positions, takes no higher number, and one past it is refused at startup. Keep the list short — each entry is a separate fetch every three hours. One caveat worth knowing: a satellite’s orbital inclination bounds the latitudes it can appear over. Hubble (hst = 20580), inclined 28.5°, never climbs usefully above the horizon for stations poleward of about ±35° latitude — most of Europe and much of North America would see a permanent “no visible pass”, which is the truth, not a bug. The defaults avoid this: the ISS (51.6°) and Tiangong (41.5°) put on the show for essentially everyone.

Comets

Comet orbital elements are the MPC’s published CometEls.txt — one ~160 KB file carrying every comet with a current orbit, cached as wxskyfield_comets.txt in the same wxskyfield directory as the satellite elements. It follows the satellites’ fetch shape at a gentler cadence: fetched at install unless the cached file is less than two days old, at any weewxd startup that finds it missing or stale, then about every two days, on a worker thread that never blocks reports — written atomically, the old file kept on any failure, and any failure, whatever the answer, waiting the full two days before the next try. Set comet_downloads = false in the [Skyfield] section and the extension fetches nothing, ever: an air-gapped station maintains the one wxskyfield_comets.txt file by any means it likes (it is the MPC file verbatim). Unlike satellite elements there is no age cutoff — two-body comet elements degrade gracefully over months, not days — and weectl extension uninstall leaves the cache file, like the satellite elements. The MPC drops comets that have faded from observability, so a configured comet can vanish from a fresh download: its tags then read “N/A” with a once-per-crossing log warning naming it — see the comet tags.

Serving every Hipparcos star

Nothing to do: as of 2.0 the complete Hipparcos catalog ships with the extension (as wxskyfield_stars.dat.gz), so every catalog star is addressable by number ($almanac.hip_57939.rise) and The Sky page’s dome plots the whole field down to star_mag_limit out of the box. Before 2.0 this took downloading hip_main.dat yourself and placing it in WeeWX’s user directory; if you did, that copy is now redundant — the extension no longer reads it, and it can be deleted.

Why require Python 3.9 or later?

weewx-skyfield uses timezone-aware date features which do not work with Python 2, nor in versions of Python 3 earlier than 3.9.

Why the DE421 ephemeris (and not DE440)?

Short answer: the accuracy difference is invisible at the precision a report displays, and DE421 is half the size. The full reasoning, with the arcsecond arithmetic, is on Accuracy and conventions.

Uninstalling 

weectl extension uninstall weewx-skyfield

Reports revert to WeeWX’s built-in almanac on the next restart. One thing is deliberately left behind: the cached orbital elements in the wxskyfield directory beside your SQLite database. Delete that directory yourself if you want them gone. See Upgrading for what changes between releases.

Testing

A pytest test suite lives in the tests directory of the repository. It exercises the Skyfield almanac (sun/moon rise/set/transit, twilight horizons, equinoxes/solstices, moon phases, positions, magnitudes/sizes/phases, named stars, satellites and passes, and polar day/night edge cases). It also contains two permanent audits: one verifying that, with PyEphem installed, everything WeeWX’s built-in almanac can do still works (including direct PyEphem attributes such as $almanac.moon.a_epoch); and one verifying that on a system without PyEphem, all standard-skin tags (and much more) work with Skyfield alone. Run the suite from the root of the repository with the Python from your WeeWX virtual environment (WeeWX, Skyfield and pytest must be installed in that environment):

/home/weewx/weewx-venv/bin/python -m pytest tests

The star tests use the bundled Hipparcos catalog and the satellite tests use archived orbital-element fixtures in tests/data, all part of the repository, so the suite never touches the network.

weewx-skyfield is Copyright © 2022–2026 John A Kline and is licensed under the GNU Public License v3.