zstarview

See the sky from anywhere, at any time -- even when it is cloudy or the Sun is up.

Zenith Star View is a desktop sky-scene simulator that combines the celestial sphere with atmospheric conditions, terrain, cityscapes, and other features around the horizon for a chosen location.

It renders an all-sky view with stars, the Sun, Moon, planets, deep-sky objects, and guide overlays. Locations can be set by city or viewpoint name, direct coordinates, online place search, or supported Google Maps URLs. When enabled, it can also add real-time cloud imagery, terrain horizon, urban outlines, night lights, nearby aircraft, and the ISS/JWST/Voyager 1/Voyager 2/Parker/Europa Clipper/Lucy/Psyche/JUICE/Solar Orbiter/BepiColombo artificial satellite overlays. It also supports small blue-dot water surfaces and an optional false-color AKARI IR dust-map layer. The default AKARI display palette combines the 90 and 140 micrometre maps; the preparation command caches all four available bands by default.

https://github.com/user-attachments/assets/b0a4e340-1089-4256-9c48-b795d5c7b200

Timelapse of the sky viewed from Matsue Station.

Screen descriptions

This view shows the night sky over a Japanese city, displayed with -p "Matsue Station" -A5 -Anw. The mouse is hovering near Vega, so the asterism it belongs to, the Summer Triangle, is shown. Buildings are displayed as an urban outline.

Clouds are visible on the left side of the image, which is the western sky, rendered as a halftone pattern of circular dots. Clouds are rendered from cloud amounts estimated from satellite data such as GOES and Himawari.

Building data is generally obtained from Overture Maps, but PLATEAU data is also available for some Japanese cities. This screenshot uses PLATEAU data.

This view shows Atlanta airport and the busy airspace above it, with more than ten aircraft visible. Aircraft trails are rendered as purple ribbons, and the ellipse below the horizon marks the never-rises region: the part of the celestial sphere that never comes above the horizon. The celestial equator and ecliptic are shown as dashed reference lines.

The celestial equator is a great circle whose normal axis is the Earth's rotation axis, the line connecting the north and south celestial poles. The never-rises boundary is a smaller circle around the same axis.

Note: To display aircraft as ribbons, specify -a 0.4 or another opacity value in the CLI. In zstarview-gui, set Aircraft opacity to 0.4 or another value in the Overlays tab of the startup dialog.

This view looks straight up from Salar de Uyuni, known as one of the flattest places in the world. The horizon forms an almost complete circle around the view because the difference in elevation along the horizon is very small. The -V9 option displays stars down to visual magnitude 9, while -s5 makes the stars slightly larger than the default so that the smaller stars stand out. --akari-ir-bands 0.3 enhances the far-infrared dust map.

Note: higher magnitude limits increase rendering time. See about magnitude limit.

This view is from a tower 108 meters above the ground, with the viewing altitude lowered slightly to -A-5 degrees. Some towers, such as Kobe Port Tower, have their locations and heights registered in the internal database. Use --list-viewpoints t to list the available tower names, or --list-viewpoints m to list the available mountain names. This view also uses night lights, a dataset of the brightness of the ground as seen from space, which makes the ground glow differently over urban and sea areas.

This view uses -A40 to change the altitude of the viewing direction and shows a view looking upward into the sky. The field of view reaches 90 degrees at the edge of the screen, producing a subtle fisheye-lens effect.

The Moon is enlarged to 5x its normal apparent size after the mouse is moved over it. The enlargement makes the Moon's lunar phase—the shape of its illuminated and dark portions—easier to see. In the default bright-body mode, the normal Moon marker also uses a compact phase-aware outline. Unlike stars and planets, which are drawn according to visual magnitude, the Moon is rendered as a disk using its apparent angular size.

This view shows a mountainous region of Switzerland, where steep terrain is visible along the horizon. Because the Sun is above the horizon, the sky is colored rather than fully dark. Terrain ridges are drawn in olive.

For cloud rendering, most of Europe is outside the coverage of GOES and Himawari, so clouds are not drawn by default. Experimental support is available through --geo-satellite true, which processes cloud imagery from a geostationary satellite.

This view is a star-field image generated with zstarview-export-image, rather than a GUI application screenshot. The object search option --search "Torifune" is used to show the position of the minor body. Osaka Castle, a Japanese building, is visible on the right.

This view shows a typhoon moving near Tokyo. The red marker shows the typhoon, and the blue diagonal lines show precipitation predicted by a forecast model. Unlike observation-based layers such as clouds, this forecast may differ from the precipitation that actually occurs. The number of lines represents the forecast amount of precipitation.

Forecast precipitation is enabled by setting --precipitation-opacity to a positive value. The first time it is enabled, you must agree to the Open-Meteo Free API terms.

This view shows observed Global Meteor Network meteor trails over Budapest. The trails are drawn in the directions recorded at observation time, with brighter tapered marks for the meteor paths and compact age labels such as -56h and -67h. The image was captured during the Perseid meteor shower, so an especially large number of trails is visible.

Meteor trails are enabled with a positive --meteor-trails-opacity value. Use --meteor-trails-max-candidates to limit the number of displayed trails.

Installation (Recommended: pipx)

Zstarview is intended to be installed using pipx.

pipx install zstarview

Upgrade:

pipx upgrade zstarview

Note: Linux x86_64 is the primary tested platform. The cloud-disc path no longer depends on pyresample, so its previous Windows on Arm64 installation blocker has been removed.

First run check:

zstarview-gui

This opens the startup dialog first. Use zstarview-gui for the default GUI launch flow after installation. If you select City as the location source and press Auto Search, the startup dialog fills in your current location automatically.

• Optional coastline data: zstarview-download-coastline --all (details)
• Optional AKARI IR bands data: zstarview-download-akari-ir-bands (details)
• Optional urban outline data: pipxu install -f overturemaps; Windows Arm64 users should see the full instructions.

Highlights

• Stars: the sky view shows stars from the selected catalog, with asterisms and other overlays layered on top.
• Solar-system bodies: supports Sun, Moon, and major planets.
• Deep-sky objects: named galaxies/open clusters/globular clusters are shown as soft blue extents.
• Asterism overlay: popular line patterns are shown as dim guide lines, alongside other sky guides such as the never-rises region, which uses a distinct neutral gray, plus the zenith and celestial pole markers.
• Satellite cloud imagery and sky-color disc: real-time Himawari/GOES satellite data are downloaded and rendered as a stylized hatched overlay, with the sky-color disc still visible beneath the clouds. The default width preset uses 50 stripes whose visible width varies with cloud amount. An experimental Geo-satellite path is available for Europe-band observers when --geo-satellite true is set.
• Aircraft and artificial satellite overlays: nearby aircraft from OpenSky can be drawn on the sky view, and ISS, JWST, Voyager 1, Voyager 2, Parker, Europa Clipper, Lucy, Psyche, JUICE, Solar Orbiter, and BepiColombo can be drawn as small purple markers between the planet and aircraft layers. ISS uses wheretheiss.at with CelesTrak fallback, while the other spacecraft use JPL Horizons.
• Tropical cyclone overlay: active hurricanes / typhoons from a public ArcGIS Active_Hurricanes_v1 FeatureServer can be shown as small markers with projected current-position tracking and a distance cutoff.
• Fresh current caches are reused for up to 24 hours for both the ISS cache and the Horizons-backed spacecraft cache.
• Terrain horizon and earth guide: Copernicus DEM data can be used to render the local terrain skyline and ground region, with a separate below-horizon continental hatch layer for orientation.
• Urban outline overlay: major rooflines are drawn for the current viewpoint, with optional distant skyscrapers in dense urban areas.
• Night lights overlay: The 2025 annual VIIRS Nighttime Lights VNL v2.2 GeoTIFF is downloaded from a GitHub Release on demand, cached locally, and rendered as a separate glow layer above the horizon and terrain ridges.
• Flexible location input: start from a city, tower, mountain, lat/lon, or online place/station search.
• Adjustable view center: change the view center from the CLI or with the arrow keys.
• Python support: routinely tested on CPython 3.10, 3.11, 3.12, 3.13, and 3.14.

Entry Points

This package provides three entry points:

• zstarview-gui for the interactive startup dialog and GUI launcher, with its own startup profile separate from the legacy CLI config.
• zstarview for GUI launches driven by command-line options, sharing the same option families described in the main README and the CLI reference docs.
• zstarview-export-image for headless one-shot image export, using the same option families as zstarview where applicable.

Code, Data Licenses, and Credits

• Code: MIT License. See LICENSE.
• Bundled and runtime-fetched data may be subject to their own licenses, attribution rules, or service terms.
• See the main project README for the full credits and third-party data notes.

Links

• Homepage: https://github.com/tos-kamiya/zstarview
• Documentation: https://github.com/tos-kamiya/zstarview#readme
• Issues: https://github.com/tos-kamiya/zstarview/issues