celery/celery · error · ImproperlyConfigured

You need to install the ephem library to use solar schedules

Error message

You need to install the ephem library to use solar schedules.
Please install by:

    $ pip install celery[solar]

What it means

ImproperlyConfigured raised in solar.__init__ (schedules.py:805) when the 'ephem' astronomy library cannot be imported. celery's solar schedule depends on ephem to compute sunrise/sunset/transit times for a given latitude/longitude and event.

Source

Thrown at celery/schedules.py:805

    }
    _use_center_l = {
        'dawn_astronomical': True,
        'dawn_nautical': True,
        'dawn_civil': True,
        'sunrise': False,
        'solar_noon': False,
        'sunset': False,
        'dusk_civil': True,
        'dusk_nautical': True,
        'dusk_astronomical': True,
    }

    def __init__(self, event: str, lat: int | float, lon: int | float, **
                 kwargs: Any) -> None:
        try:
            self.ephem = __import__('ephem')
        except ImportError as exc:
            raise ImproperlyConfigured(SOLAR_EPHEM_NOT_INSTALLED) from exc
        self.event = event
        self.lat = lat
        self.lon = lon
        super().__init__(**kwargs)

        if event not in self._all_events:
            raise ValueError(SOLAR_INVALID_EVENT.format(
                event=event, all_events=', '.join(sorted(self._all_events)),
            ))
        if lat < -90 or lat > 90:
            raise ValueError(SOLAR_INVALID_LATITUDE.format(lat=lat))
        if lon < -180 or lon > 180:
            raise ValueError(SOLAR_INVALID_LONGITUDE.format(lon=lon))

        cal = self.ephem.Observer()
        cal.lat = str(lat)
        cal.lon = str(lon)
        cal.elev = 0

View on GitHub (pinned to 3511be41db)

Solutions

1. Install the solar extra: pip install celery[solar] (or pip install ephem directly).
2. Pin ephem in requirements.txt / pyproject to avoid surprise removals.
3. Rebuild Docker/CI images to include the extra after adding it.
4. If you do not actually need solar schedules, remove the solar(...) usage to drop the dependency.

Example fix

# before (env missing ephem)
from celery.schedules import solar
beat_schedule={'sun': {'task':'t', 'schedule': solar('sunrise', 40, -3)}}
# after
# shell:
#   pip install celery[solar]
# then the same Python code works unchanged

def require_solar_extra():
    try:
        import ephem  # noqa
    except ImportError as e:
        raise RuntimeError('Install celery[solar] (ephem) before using solar schedules') from e

require_solar_extra()
from celery.schedules import solar

def solar_available() -> bool:
    try:
        import ephem  # noqa
        return True
    except ImportError:
        return False

try:
    from celery.schedules import solar
    schedule = solar('sunrise', lat, lon)
except Exception as e:  # ImproperlyConfigured
    log.warning('solar unavailable, skipping: %s', e)
    schedule = None

When it happens

Trigger: Instantiating solar(event, lat, lon) without the ephem package installed in the environment. The __import__('ephem') at line 803 raises ImportError, which celery re-raises as ImproperlyConfigured with this message.

Common situations: Fresh deployment missing the solar extra; Docker/CI image that only installed base celery; upgrading celery and forgetting the optional dependency; conda vs pip environment mismatch.

Related errors

• You must install google-cloud-firestore to use gcs backend
• You need to install the pymongo library to use the MongoDB b
• You need to install the redis library in order to use the Re
• You need to install the redis library with support of sentin
• You must install boto3 to use s3 backend

AI-assisted analysis of celery/celery@3511be41db (2026-08-09). Data as JSON: /api/errors/48628c07ef2d2a4e. Report an issue: GitHub.