System Directories#

In this documentation we refer to a few different directories that Gaia Sky uses to store data and configuration settings: $GS_DATA, $GS_CONFIG, and $GS_CACHE.

  • $GS_DATA — contains some essential files and directories for Gaia Sky to run properly. For example:

    • $GS_DATA/camera — storage point for camera path and keyframe files.

    • $GS_DATA/mpcdi — MPCDI projection configuration files for planetarium setups.

    • $GS_DATA/frames — default save location for the frame output mode.

    • $GS_DATA/screenshots — default save location for screenshots.

    • $GS_DATA/crashreports — whenever Gaia Sky crashes, a crash report is stored at this location.

    • $GS_DATA/log — contains the full Gaia Sky log of the last session. Only the last session’s log is kept.

    • $GS_DATA/data — also referred to as simply $data, this is the default dataset save location. All datasets are stored in this location by default (can be changed from the dataset manager).

    • $GS_DATA/data/cache — downloaded files that are cheap to re-fetch but slow to obtain, such as TLE orbital elements for artificial satellites. Safe to delete.

    • $GS_DATA/data/tmp — temporary files created while downloading datasets. Safe to delete.

    • $GS_DATA/data/procedural-planet-textures — where procedurally generated planet textures are exported, if the option to export them is enabled.

  • $GS_CONFIG — contains the configuration files, the bookmarks folder with your bookmarks, and the mappings folder with the keyboard and gamepad mappings files.

  • $GS_CACHE — contains cached files that Gaia Sky can download again at any time: images shown in the dataset manager and in the data info window (including Wikipedia thumbnails), and the shadercache folder with compiled OpenGL shaders. Safe to delete at any time; the next run will download or recompile whatever it needs. You can also clear just the shader cache from the system preferences.

The locations of $GS_DATA, $GS_CONFIG and $GS_CACHE depend on the operating system:

  • Linux — as of Gaia Sky 2.2.0, the Linux release of Gaia Sky uses the XDG base directory specification. If the XDG_DATA_HOME, XDG_CONFIG_HOME or XDG_CACHE_HOME environment variables are set, they take precedence over the defaults below.

    • $GS_DATA = ~/.local/share/gaiasky/

    • $GS_CONFIG = ~/.config/gaiasky/

    • $GS_CACHE = ~/.cache/gaiasky/

  • Windows and macOS — the .gaiasky directory in the user home directory is used for both $GS_DATA and $GS_CONFIG, so:

    • $GS_DATA = $GS_CONFIG = [User.Home]/.gaiasky/

      • [User.Home] on Windows is typically in C:\Users\[username].

      • [User.Home] on macOS is typically in /Users/[username].

    • $GS_CONFIG = $GS_DATA

    • $GS_CACHE = $GS_DATA

Datasets location#

By default, Gaia Sky stores the downloaded datasets in the $GS_DATA/data directory. The location where the datasets are saved is referred to as $data. The actual location of $data is stored in the configuration file (key data::location) and can be changed in the dataset manager window at startup.

  • $data = $GS_DATA/data

Because $data can be moved anywhere, the cache, tmp and procedural-planet-textures folders listed above are also relative to it, not to $GS_DATA.

Logs and crash reports#

For every Gaia Sky session, a system log is stored in the directory $GS_DATA/log. Logs are overwritten with each new session, so only the last log is effectively available at any given time.

  • $GS_DATA/log/gaiasky_log_lastsession.txt — full log of the last Gaia Sky session.

Crash reports are stored in $GS_DATA/crashreports whenever Gaia Sky crashes. If that happens, please create a new issue in https://codeberg.org/gaiasky/gaiasky/issues, and attach the crash report. Additionally, also attach the session log.

  • $GS_DATA/crashreports/gaiasky_crash_[$DATE].txt — crash reports.