Running Gaia Sky

This section contains information on how to run the software depending on the install method.

Running regular installation

If you installed the software using an installer or a package manager system (rpm, deb), you just need to use the standard running procedures of your Operating System to run the application.


Just type gaiasky in a terminal or use your favourite desktop environment search engine to run the Gaia Sky launcher.


In windows, this means clicking on Start and then browsing the start menu folder Gaia Sky. You can run the executable from there.


Locate the launcher in your install directory (usually /Applications) and double click on it.

Code and pakcage

However, if you are a maverick and do not like installers, you can also run the Gaia Sky directly from the source code in GitHub or using the tgz package.

Running from tar.gz package

You can also run the software using the tar.gz package without need for an installation. To do so, extract the archive to your desired location and run the gaiasky script (Linux, macOS), or the gaiasky.cmd batch file (Windows).

$  tar -xzvf gaiasky-[version].tar.gz
$  cd gaiasky-[version]
$  gaiasky #Linux/macOS
$  .\gaiasky.cmd #Windows

Running from source


If you want to compile the source code, you will need the following:

  • JDK15+

  • git

Please, be aware that only tags are guaranteed to work (here). The master branch holds the development version and the configuration files are possibly messed up and not ready to work out-of-the-box. So remember to use a tag version if you want to run it right away from source.

First, clone the repository:

$  git clone

Getting the catalog data


As of version 2.1.0, Gaia Sky provides a self-contained download manager to get all the data packs available.

The base-data pack is necessary for Gaia Sky to run, and contains the Solar System, the Milky Way model, etc. Catalog files are optional but recommended if you want to see any stars at all. You can bring up the download manager at any time by clicking on the button Data download in the preferences window, data tab. More information on the download manager can be found in Dataset manager.

You can also download the data packs manually here.

Compiling and running

To compile the code and run Gaia Sky run the following.

$  gradlew core:run

If you want to pass CLI arguments via gradle, just use the gradle --args argument (gradlew core:run --args='-vr').

Tip: Gaia Sky will check that you are using a version compatible with Java 15 when running the build. You can skip this check by setting the following environment variable to false in the context of gradle:

$  export GS_JAVA_VERSION_CHECK=false

In order to pull the latest changes from the GitHub repository:

$  git pull

CLI arguments

Gaia Sky offers a few command line arguments. Run gaiasky -h for more information.

$  gaiasky -h
Usage: gaiasky [options]
    -h, --help
      Show program options and usage information.
    -v, --version
      List Gaia Sky version and relevant information.
      Default: false
    -i, --asciiart
      Add nice ascii art to --version information.
      Default: false
    -s, --skip-welcome
      Skip the welcome screen if possible (base-data package must be present).
      Default: false
    -p, --properties
      Specify the location of the properties file.
    -a, --assets
      Specify the location of the assets folder. If not present, the default
      assets location (in the installation folder) is used.
    -vr, --openvr
      Launch in Virtual Reality mode. Gaia Sky will attempt to create a VR
      context through OpenVR.
      Default: false
    -e, --externalview
      Create a window with a view of the scene and no UI.
      Default: false
    -n, --noscript
      Do not start the scripting server. Useful to run more than one Gaia Sky
      instance at once in the same machine.
      Default: false
    -d, --debug
      Launch in debug mode. Prints out debug information from Gaia Sky to the
      Default: false
    -g, --gpudebug
      Activate OpenGL debug mode. Prints out debug information from OpenGL to
      the standard output.
      Default: false
      Activate safe graphics mode. This forces the creation of an OpenGL 3.2
      context, and disables float buffers and tessellation.
      Default: false

Packaging the software

Gaia Sky can be exported to a folder to be run as a standalone app. Right now, doing so is only supported from Linux. You will need the utility help2man in your path. Remember to restart the gradle daemon after installing it.

$  gradlew core:dist

That will create a new folder called releases/gaiasky-[version].[revison] with the exported application. Run scripts are provided with the name gaiasky (Linux, macOS) and gaiasky.cmd (Windows).

Also, to export Gaia Sky into a tar.gz archive file, run the following.

$  gradlew core:createTar

In order to produce the desktop installers for the various systems you need a licensed version of Install4j. Additionally, you need a certificate for signing the Windows packages in $GS/assets/cert/cert.pfx. Then, you need to run:

$  gradlew core:pack -PwinKeystorePassword=PASSWORD

Where PASSWORD is the password of the certificate. These command will produce the different OS packages (.exe, .dmg, .deb, .rpm, etc.) of Gaia Sky into releases/packages-[version].[revision] folder.