{"id":2494,"library":"ephem","title":"PyEphem","description":"PyEphem is a Python library for computing positions of the planets and stars. It provides precise astronomical calculations, including positions of celestial bodies, times of sunrise/sunset, moon phases, and more, based on standard algorithms. The current version is 4.2.1, with releases typically occurring a few times a year for minor updates and bug fixes, and major versions every 1-2 years.","status":"active","version":"4.2.1","language":"en","source_language":"en","source_url":"https://github.com/brandon-rhodes/pyephem","tags":["astronomy","celestial mechanics","astrophysics","calculations","time"],"install":[{"cmd":"pip install ephem","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"ephem","correct":"import ephem"},{"note":"Most users 'import ephem' and then access objects like 'ephem.Observer', 'ephem.Mars', etc.","wrong":"from ephem import Observer # While technically correct, 'import ephem' is more common for accessing other body objects.","symbol":"Observer","correct":"import ephem\nobserver = ephem.Observer()"}],"quickstart":{"code":"import ephem\nimport datetime\n\n# Create an observer at a specific location and time (UTC)\nboston = ephem.Observer()\nboston.lat = '42.35'  # North latitude\nboston.lon = '-71.05' # West longitude\nboston.elevation = 0  # Meters above sea level\nboston.date = datetime.datetime.utcnow() # Set date to current UTC time\n\n# Create a planet object (Mars)\nmars = ephem.Mars()\n\n# Compute its position for the observer's location and time\nmars.compute(boston)\n\n# Print celestial coordinates, converting radians to degrees for readability\nprint(f\"Mars Right Ascension (RA): {ephem.degrees(mars.ra)}\")\nprint(f\"Mars Declination (Dec): {ephem.degrees(mars.dec)}\")\nprint(f\"Mars Azimuth: {ephem.degrees(mars.az)}\")\nprint(f\"Mars Altitude: {ephem.degrees(mars.alt)}\")\nprint(f\"Mars Distance: {mars.range:.2f} AU\")","lang":"python","description":"This quickstart demonstrates how to create an observer, set its location and time (important: use UTC!), create a celestial body, compute its position relative to the observer, and print its coordinates, explicitly converting radian outputs to degrees for human readability."},"warnings":[{"fix":"Always use `ephem.degrees(value)` when printing angles to convert radians to degrees, or when setting angles if your input is in degrees (e.g., `observer.lat = ephem.degrees('42.35')` if '42.35' was in degrees but ephem expected radians, though in lat/lon strings are parsed correctly).","message":"PyEphem uses radians for all internal angle calculations and returns values in radians by default. For human-readable output or input, explicitly convert using `ephem.degrees()`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always provide UTC `datetime` objects to `observer.date` (e.g., `datetime.datetime.utcnow()`, or a timezone-aware `datetime` object converted to UTC). Alternatively, use `ephem.localtime()` to convert a UTC date to local time before setting, if you specifically need local time input.","message":"PyEphem operates internally on UTC (Coordinated Universal Time). Providing naive `datetime` objects that are meant to be local time will be misinterpreted as UTC, leading to incorrect calculations.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always remember to call `body.compute(observer)` after modifying `observer.date` or if you're working with a new `Observer` instance.","message":"After changing an observer's date or creating a new observer, you MUST call the `.compute(observer)` method on celestial body objects to update their positions for the new time/location. Failing to do so will result in calculations based on the body's default epoch or previous observer's time.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use string inputs like `'42.35'` for lat/lon for clarity, which PyEphem parses correctly. If using floats, ensure they are in radians or apply `ephem.degrees()` for conversion if you are using degree values.","message":"Latitude and longitude strings can be provided directly to `observer.lat` and `observer.lon` (e.g., `'42.35'`), but ensure you understand the sign conventions: positive for North/East, negative for South/West. If providing floats, they are assumed to be in radians unless explicitly converted.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}