Astral Library

3.2 · active · verified Sun Apr 12

Astral is a Python package for calculating the times of various aspects of the sun and moon, including dawn, sunrise, noon, sunset, dusk, and moon phases. It also provides functions for solar azimuth and elevation. The library includes a self-contained geocoder for looking up location information by name. The current version is 3.2, and it maintains an active release cadence, frequently adding new features and improvements.

Warnings

breaking In version 3.0, `astral` migrated from `pytz` to Python's built-in `zoneinfo` for timezone handling. This means for Python versions prior to 3.9, you will need to explicitly install `backports.zoneinfo` to ensure timezone functionality works correctly.
Fix: For Python < 3.9, install `backports.zoneinfo`: `pip install backports.zoneinfo`. Ensure your code handles `zoneinfo` objects instead of `pytz` timezone objects.
deprecated The direct use of `astral.Astral()` and accessing cities like `a['London']` is part of an older API and may not function as expected or be supported in future versions. The `Astral` class itself was removed in version 3.0.
Fix: Migrate to using `astral.geocoder.lookup(name, database())` to retrieve `LocationInfo` objects, and then access the `observer` attribute to get the `Observer` object.
gotcha When passing `datetime` objects to functions like `sun()` or `azimuth()`, if the datetime object is 'naive' (i.e., lacks timezone information), `astral` will assume it represents a UTC time. This can lead to incorrect calculations if the user expects local time.
Fix: Always use timezone-aware `datetime` objects. For Python >= 3.9, use `zoneinfo.ZoneInfo('timezone_name')`. For Python < 3.9, ensure `backports.zoneinfo` is installed and use its `ZoneInfo` for timezone localization.
gotcha The Google Geocoder (`astral.geocoder.GoogleGeocoder`) requires an API key, as mandated by Google. Attempting to use it without providing a valid API key will result in errors.
Fix: When initializing `GoogleGeocoder`, pass your Google Maps API key as the `api_key` parameter: `GoogleGeocoder(api_key='YOUR_API_KEY')`. For simple location lookups without an API key, use the built-in `astral.geocoder.database()` and `lookup()`.
gotcha The `astral` package currently does not adjust solar elevation calculations for changes in observer elevation. While the effect is generally very small, users requiring extreme precision for high elevations might find this behavior unexpected.
Fix: Be aware of this limitation when performing highly precise solar elevation calculations, particularly for observers at very high altitudes. The documentation indicates the difference is usually negligible for most applications.

Install

pip install astral Install latest version

Imports

LocationInfo

from astral.location import LocationInfo

Observer

from astral.geocoder import lookup
from astral import Observer

sun
```
from astral.sun import sun
```
moonphase
```
from astral.moon import moonphase
```
Astral
```
from astral.geocoder import lookup, database
city = lookup("London", database())
```
The `Astral` class and direct dictionary-like access for cities (`a[city_name]`) are part of an older API. Modern usage prefers `lookup` from `astral.geocoder` to retrieve `LocationInfo` objects.

Quickstart

This example demonstrates how to define a location using `LocationInfo`, retrieve an `Observer` object, and then calculate the sun's key events (dawn, sunrise, noon, sunset, dusk) for a specific date.

import datetime
from astral.location import LocationInfo
from astral.sun import sun

# Define a location
l = LocationInfo('London', 'England', 'Europe/London', 51.5, 0.1)

# Get an Observer object from the LocationInfo
observer = l.observer

# Get sun times for today
today = datetime.date.today()
s = sun(observer, date=today)

print(f"Sun Information for {l.name} on {today}:")
print(f"  Dawn: {s['dawn']}")
print(f"  Sunrise: {s['sunrise']}")
print(f"  Noon: {s['noon']}")
print(f"  Sunset: {s['sunset']}")
print(f"  Dusk: {s['dusk']}")

view raw JSON →