{"id":5423,"library":"pyswisseph","title":"PySwissEphe - Swiss Ephemeris","description":"PySwissEphe is a Python extension providing access to the powerful Swiss Ephemeris library, a high-precision astronomical calculation engine. It allows for calculation of planetary positions, houses, aspects, and other celestial data. Currently at version 2.10.3.2, the library maintains a steady release cadence, often updating to reflect new versions of the underlying Swiss Ephemeris C code.","status":"active","version":"2.10.3.2","language":"en","source_language":"en","source_url":"https://github.com/astrorigin/pyswisseph","tags":["astrology","astronomy","ephemeris","celestial mechanics"],"install":[{"cmd":"pip install pyswisseph","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"The convention is to import swisseph and alias it as swe for brevity and consistency with the original Swiss Ephemeris API.","symbol":"swisseph","correct":"import swisseph as swe"}],"quickstart":{"code":"import swisseph as swe\nimport os\n\n# IMPORTANT: For accurate calculations, you need to download the Swiss Ephemeris\n# data files (e.g., 'se1900-2050.se1', 'seasr.se1') from the official website\n# (www.astro.com/swisseph/sweph_e.htm) and place them in a directory.\n# For this example, we create an empty 'swefiles' directory in the current\n# working directory. Calculations will fail or return errors without the actual files.\n\nephe_dir = 'swefiles'\nif not os.path.exists(ephe_dir):\n    os.makedirs(ephe_dir)\n    print(f\"Created directory '{ephe_dir}'. Please populate it with Swiss Ephemeris data files.\")\n\n# Set the path to the ephemeris data files\nswe.swe_set_ephe_path(ephe_dir)\n\n# Define a Julian Day (UT - Universal Time) for calculation\n# January 1, 2024, 12:00 UT\njd_ut = swe.swe_julday(2024, 1, 1, 12.0, swe.SE_GREG_CAL)\n\n# Define calculation flags: use default Swiss Ephemeris, calculate speed\nflags = swe.SEFLG_SWIEPH | swe.SEFLG_SPEED\n\n# Calculate Mars' position (SE_MARS)\n# xx will contain: [longitude, latitude, distance, speed_longitude, speed_latitude, speed_distance]\nxx, ret = swe.swe_calc_ut(jd_ut, swe.SE_MARS, flags)\n\nif ret >= 0:\n    print(f\"Mars' position on 2024-01-01 12:00 UT:\")\n    print(f\"  Longitude: {xx[0]:.4f}°\")\n    print(f\"  Latitude:  {xx[1]:.4f}°\")\n    print(f\"  Distance:  {xx[2]:.4f} AU\")\n    print(f\"  Speed Longitude: {xx[3]:.4f}°/day\")\nelse:\n    print(f\"Error calculating Mars' position. Make sure '{ephe_dir}' contains required '.se1' files.\")\n    print(f\"Swiss Ephemeris error: {swe.swe_get_serr_string(ret)}\")\n","lang":"python","description":"This quickstart demonstrates how to initialize PySwissEphe, set the ephemeris data path, and calculate a planet's position. Note that accurate calculations require downloading Swiss Ephemeris data files (.se1) and placing them in the specified `ephe_dir`."},"warnings":[{"fix":"Download the necessary ephemeris data files from the official Swiss Ephemeris website (www.astro.com/swisseph/sweph_e.htm) and ensure the provided path is correct.","message":"The `swe.swe_set_ephe_path()` function must be called with a valid path to the Swiss Ephemeris data files (.se1). Without these files, calculations will fail, often with cryptic error messages or silently incorrect results.","severity":"gotcha","affected_versions":"All"},{"fix":"Refer to the official Swiss Ephemeris documentation and `pyswisseph` examples to understand the purpose and correct usage of these constants for your specific astrological or astronomical needs.","message":"The library exposes numerous constants (e.g., `swe.SE_JUL_CAL`, `swe.SE_SUN`, `swe.SEFLG_SWIEPH`) that control calculation parameters and celestial bodies. Misunderstanding or incorrect use of these constants can lead to inaccurate astronomical calculations without explicit Python errors.","severity":"gotcha","affected_versions":"All"},{"fix":"Always consult the release notes for both `pyswisseph` and the underlying Swiss Ephemeris C library when upgrading, and validate critical calculations after an update.","message":"As a wrapper for the Swiss Ephemeris C library, `pyswisseph` versions directly correspond to the upstream library's version. Updates to the C library can introduce breaking changes, bug fixes, or new features that subtly affect calculation precision or behavior, especially in edge cases.","severity":"breaking","affected_versions":"Dependent on upstream Swiss Ephemeris library changes"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}