Install & Compatibility
Where this runs
tested against v2.10.3.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.12
✕ build_error
✕ build_error
py 3.13
✕ build_error
✕ build_error
24MB installed
● package 24MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
swisseph
✓ import swisseph as swe
The convention is to import swisseph and alias it as swe for brevity and consistency with the original Swiss Ephemeris API.
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`.
import swisseph as swe
import os
# IMPORTANT: For accurate calculations, you need to download the Swiss Ephemeris
# data files (e.g., 'se1900-2050.se1', 'seasr.se1') from the official website
# (www.astro.com/swisseph/sweph_e.htm) and place them in a directory.
# For this example, we create an empty 'swefiles' directory in the current
# working directory. Calculations will fail or return errors without the actual files.
ephe_dir = 'swefiles'
if not os.path.exists(ephe_dir):
os.makedirs(ephe_dir)
print(f"Created directory '{ephe_dir}'. Please populate it with Swiss Ephemeris data files.")
# Set the path to the ephemeris data files
swe.swe_set_ephe_path(ephe_dir)
# Define a Julian Day (UT - Universal Time) for calculation
# January 1, 2024, 12:00 UT
jd_ut = swe.swe_julday(2024, 1, 1, 12.0, swe.SE_GREG_CAL)
# Define calculation flags: use default Swiss Ephemeris, calculate speed
flags = swe.SEFLG_SWIEPH | swe.SEFLG_SPEED
# Calculate Mars' position (SE_MARS)
# xx will contain: [longitude, latitude, distance, speed_longitude, speed_latitude, speed_distance]
xx, ret = swe.swe_calc_ut(jd_ut, swe.SE_MARS, flags)
if ret >= 0:
print(f"Mars' position on 2024-01-01 12:00 UT:")
print(f" Longitude: {xx[0]:.4f}°")
print(f" Latitude: {xx[1]:.4f}°")
print(f" Distance: {xx[2]:.4f} AU")
print(f" Speed Longitude: {xx[3]:.4f}°/day")
else:
print(f"Error calculating Mars' position. Make sure '{ephe_dir}' contains required '.se1' files.")
print(f"Swiss Ephemeris error: {swe.swe_get_serr_string(ret)}")
Debug
Known issues
gotchaThe `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.fixDownload 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.
affects: All
gotchaThe 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.fixRefer 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.
affects: All
breakingAs 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.fixAlways consult the release notes for both `pyswisseph` and the underlying Swiss Ephemeris C library when upgrading, and validate critical calculations after an update.
affects: Dependent on upstream Swiss Ephemeris library changes
Errors
Common errors & fixes
FileNotFoundError: swiss_eph_data directory not found
The pyswisseph library cannot locate the necessary Swiss Ephemeris data files (e.g., .se1, .se2) in its default search paths.
fixDownload the required `sweph` data files and place them in an accessible directory, then explicitly set the path using `pyswisseph.set_ephe_path('/path/to/your/sweph_data_directory')`. error: Microsoft Visual C++ 14.0 or greater is required.
Installing pyswisseph from source on Windows requires a C++ compiler, which is often missing if Visual Studio Build Tools are not installed.
fixDownload and install the "Build Tools for Visual Studio" from Microsoft, ensuring the "Desktop development with C++" workload is selected, or use a pre-compiled wheel if available for your Python version and architecture.
ModuleNotFoundError: No module named 'pyswisseph'
The pyswisseph package was not successfully installed, or the Python environment you are using does not have it installed.
fixInstall the package using `pip install pyswisseph` and ensure you are running your script in the Python environment where it was installed.
AttributeError: module 'pyswisseph' has no attribute 'swe_julday'
The user is attempting to call a raw Swiss Ephemeris C API function name (e.g., `swe_julday`) directly, instead of its Python-wrapped alias provided by pyswisseph.
fixUse the Pythonic function names exposed by the `pyswisseph` module; for `swe_julday`, use `pyswisseph.julday()`.
TypeError: swe_julday() takes 4 positional arguments but 3 were given
The `swe.julday` function expects four arguments: year, month, day, and hour.
fixProvide all four required arguments (year, month, day, hour) to calculate the Julian day.
```python
import swisseph as swe
# Correct: provide year, month, day, and hour
jd = swe.julday(2023, 10, 27, 12.0)
```
Upgrade
Version history
2.10.3.2latest on PyPI · released Jun 4, 2023
Audit
Dependencies
No dependency data recorded yet.