Where Stellium Reads and Writes¶

Stellium touches exactly two directories, and they are kept apart on purpose.

	Default (macOS / Linux)	Default (Windows)	Override with
Ephemeris — data; keep it	`~/.stellium/ephe/`	`C:\Users\<you>\.stellium\ephe\`	`STELLIUM_EPHE_PATH`
Cache — disposable	`~/.cache/stellium/`	`%LOCALAPPDATA%\stellium\cache\`	`STELLIUM_CACHE_DIR`

Nothing else is written anywhere. In particular Stellium does not create a .cache/ in your working directory, and importing it does not touch the disk at all.

To see where those two actually resolved on your machine — and whether an environment variable or the default put them there:

stellium cache info

🗂️  Stellium paths
============================================================
Cache (disposable):  /home/you/.cache/stellium
                     default — override with STELLIUM_CACHE_DIR
Ephemeris (data):    /home/you/.stellium/ephe
                     default — override with STELLIUM_EPHE_PATH

The ephemeris directory — data¶

Stellium bundles enough Swiss Ephemeris data to cover 1800–2999 CE and copies it to ~/.stellium/ephe/ on first use, so most users never need to download anything. Reach for stellium ephemeris download only if you need coverage outside that range, and stellium ephemeris download-asteroid for extra asteroid or TNO files.

Keep this directory. Anything you downloaded into it — asteroids, TNOs, a wider date range — is slow to fetch again and is not re-created for you.

Pointing at an existing ephemeris folder¶

Useful for portable installs, read-only home directories (Docker, Lambda, shared hosts), or reusing a folder you already maintain for another astrology tool. In order of precedence:

# 1. Explicit argument — wins over everything else
from stellium import ChartBuilder
from stellium.engines.ephemeris import SwissEphemerisEngine

chart = (ChartBuilder.from_native(native)
    .with_ephemeris(SwissEphemerisEngine(ephe_path=r"D:\swisseph\ephe"))
    .calculate())

# 2. Environment variable — no code changes required
export STELLIUM_EPHE_PATH=/opt/swisseph/ephe       # macOS / Linux
set STELLIUM_EPHE_PATH=D:\swisseph\ephe            # Windows (cmd)
$env:STELLIUM_EPHE_PATH = "D:\swisseph\ephe"       # Windows (PowerShell)

⚠️ A custom ephemeris folder is used as-is. Stellium will not create it, and will not copy the bundled .se1 files into it. Populate it first — either copy ~/.stellium/ephe/ across, or run stellium ephemeris download after setting the variable. Otherwise you will get MissingEphemerisWarning for objects whose files aren’t there (a missing se00015.se1 means no Chiron, for instance).

The cache directory — disposable¶

Holds pickled geocoding lookups: the results of turning "Palo Alto, CA" into coordinates, so the same place is not looked up over the network twice. That is all that is cached.

It is safe to delete at any time. Nothing in it is precious, and everything in it can be regenerated.

stellium cache clear

Chart calculation is not cached. Swiss Ephemeris positions are computed in microseconds — faster than reading a cached copy back from disk — so caching them would make Stellium slower.

Why it does not live in `~/.stellium/`¶

Because a cache and your ephemeris deserve opposite treatment. ~/.cache is the directory the wider ecosystem already agrees is disposable: backup tools skip it, cleaners empty it, CI images mount it. Keeping the two apart means “clear Stellium’s junk” can never point at asteroid files you spent time downloading.

XDG_CACHE_HOME is honoured if you set it. On macOS the default is ~/.cache rather than ~/Library/Caches, because Stellium is a developer-facing library and that is where its users look — set XDG_CACHE_HOME if you prefer otherwise.

Portable installs, and read-only home directories¶

If you run a portable or embedded Python, or $HOME is read-only (Docker, Lambda, shared hosts), set both variables and Stellium will never write to your home drive.

Windows — portable Python, project on `D:`¶

# PowerShell — keep everything on D:, next to the project
$env:STELLIUM_EPHE_PATH = "D:\Astrology\Stellium\ephe"
$env:STELLIUM_CACHE_DIR = "D:\Astrology\Stellium\cache"

# Make it stick across sessions (current user; no admin needed):
[Environment]::SetEnvironmentVariable("STELLIUM_EPHE_PATH", "D:\Astrology\Stellium\ephe",  "User")
[Environment]::SetEnvironmentVariable("STELLIUM_CACHE_DIR", "D:\Astrology\Stellium\cache", "User")

# Verify — prints both paths and where each one came from:
stellium cache info

Then populate the ephemeris folder once (it is used as-is, remember):

# Either copy what Stellium already unpacked...
Copy-Item "$env:USERPROFILE\.stellium\ephe\*" "D:\Astrology\Stellium\ephe\"

# ...or download fresh, now that the variable points where you want it:
stellium ephemeris download

macOS / Linux¶

export STELLIUM_EPHE_PATH=/opt/stellium/ephe
export STELLIUM_CACHE_DIR=/opt/stellium/cache

The cache directory is created for you on first write. The ephemeris directory is not — see the warning above.

Troubleshooting¶

“Stellium can’t find my ephemeris file / I get a MissingEphemerisWarning.” Run stellium cache info and check the ephemeris path is the folder you think it is. If an environment variable is redirecting it, that folder is used as-is — the file has to actually be in it. Then:

from stellium.data.paths import get_ephe_dir, has_ephe_file
print(get_ephe_dir())
print(has_ephe_file("se00015.se1"))   # Chiron

“A .cache/ folder appeared in my project directory.” That was a bug in Stellium ≤ 0.21.0: the cache defaulted to a relative path, so it was created wherever you happened to launch Python — and it grew without bound. Fixed; the directory is now absolute. Any stray .cache/ folders left behind by an older version are safe to delete.