Installation#

The sections below contain information on the minimum hardware requirements, on how to install the software on each operating system, how to run it from source, and the available command line arguments.

System requirements#

Here are the minimum requirements to run this software:

Operating system

Linux / Windows 10+ / macOS

Architecture

x86_64, ARM64 (Apple silicon, or ARM Linux via the Flatpak)

CPU

Intel Core i5 3rd Gen. 4+ cores recommended

GPU

Support for OpenGL 3.3 (4.2 recommended), 1 GB VRAM

Memory

4+ GB RAM (depends on loaded datasets)

Hard drive

1+ GB of free disk space (depends on downloaded datasets)

Download#

Gaia Sky packages are available for Linux, macOS and Windows. You can either download the Gaia Sky build for your operating system (recommended), or get the source code and compile it yourself.

Installation procedure#

Depending on your system and your personal preferences the installation procedure may vary. This section describes the installation and running process for the different operating systems and packages.

Linux#

We provide four packages that work on most distributions:

We also offer three distribution-specific packages:

  • DEB – Debian and derivatives.

  • RPM – RedHat and derivatives.

  • AUR – Arch Linux and derivatives.

Whichever package you choose, once installed you can run the gaiasky command, or use your favourite launcher to find and run it.

Flatpak#

Install the Flatpak package with the following:

flatpak install flathub space.gaiasky.GaiaSky

Then, run with:

flatpak run space.gaiasky.GaiaSky

In order to uninstall the Flatpak package, run:

flatpak uninstall --delete-data space.gaiasky.GaiaSky

AppImage#

The AppImage does not need installation. Download the package, give it execute permissions if necessary, and run it.

wget https://gaia.ari.uni-heidelberg.de/gaiasky/releases/latest/gaiasky_$VERSION_x86_64.appimage
chmod +x gaiasky_$VERSION_x86_64.appimage
./gaiasky_$VERSION_x86_64.appimage

Since the AppImage is self-contained, there is nothing to uninstall. Just delete the .appimage file (and any extracted squashfs-root folder).

Unix installer#

Download the package, give it execute permissions and run it to start the installation process. Then follow the on-screen instructions:

chmod +x gaiasky_linux_$VERSION.sh
./gaiasky_linux_$VERSION.sh

In order to uninstall, run the uninstaller that was placed in the installation folder:

/opt/gaiasky/uninstall.sh

Alternatively, you can remove the /opt/gaiasky folder and any of its shortcuts manually.

DEB package#

This is the package for Debian-based distros (Debian, Ubuntu, Mint, etc.). Download the gaiasky_$VERSION.deb file and run the following command. You need root privileges to install a DEB package in your system.

dpkg -i gaiasky_$VERSION.deb

This installs the application in the /opt/gaiasky/ folder and creates the necessary shortcuts and .desktop files.

In order to uninstall, just type:

apt remove gaiasky

RPM package#

This is the package for RPM-based distributions (Red Hat, Fedora, Mandriva, SUSE, CentOS, etc.) Download the gaiasky_linux_$VERSION.rpm file and run the following command. You need root privileges to install an RPM package in your system.

rpm --install gaiasky_linux_$VERSION.rpm

This installs the application in the /opt/gaiasky/ folder and creates the necessary shortcuts.

In order to uninstall, just type:

dnf remove gaiasky

AUR package#

We also offer an Arch User Repository (AUR) package for Arch Linux and derivatives. Install one of gaiasky, gaiasky-git or gaiasky-appimage. For example, if you use paru:

paru -S gaiasky

In order to uninstall an AUR package, use your AUR helper again:

paru -R gaiasky

Windows#

We offer a Windows installer for 64-bit systems, gaiasky_windows-x64_$VERSION.exe.

To install Gaia Sky, just double-click on the installer and then follow the on-screen instructions. You need to choose the directory where the application is to be installed.

Warning

Our Windows installation package is signed with a self-signed certificate rather than one issued by a trusted Certificate Authority. If you want Windows to recognise the signature, you can import the certificate into the system’s Trusted Root store. This can be done by downloading the public certificate file cert.pem and running the following command in a PowerShell terminal with administrator rights:

certutil -addstore "Root" cert.pem

After importing, Windows will treat the certificate as trusted, and the installation will proceed without publisher warnings.

You can also bypass the security warnings by letting Windows install apps from all sources. To do so, go to Settings > Apps > Advanced app settings, and then next to Choose where to get apps, select Anywhere. See the Microsoft article on app recommendation settings for details.

To run Gaia Sky, click on Start and then look up the Gaia Sky folder in the Start menu. You can run the executable(s) for Gaia Sky and Gaia Sky VR from there. You can also navigate to the installation folder and run the gaiasky.cmd file from a command prompt or PowerShell.

In order to uninstall the application you can use the Windows Control Panel or you can use the provided uninstaller in the Gaia Sky folder.

macOS#

We provide two ways to install on macOS:

We recommend installing via homebrew, as the subsequent updates are easier.

Homebrew#

If you use brew, you can install Gaia Sky right from your terminal. In order to install it, add our tap (third-party repository) to brew and then install the package:

# Tap the repository
brew tap gaiasky/homebrew https://codeberg.org/gaiasky/homebrew

# Install gaiasky (latest version)
brew install gaiasky
# OR: Install master development branch
brew install --HEAD gaiasky

# If you want to launch Gaia Sky from Dock or Launchpad, create a symlink
ln -sf "/opt/homebrew/opt/gaiasky/Gaia Sky.app" /Applications

In order to uninstall, run:

brew uninstall gaiasky
brew untap gaiasky/homebrew

If you created the symlink in /Applications, delete it as well:

rm "/Applications/Gaia Sky.app"

DMG package#

For macOS we provide a gaiasky_macos_$VERSION.dmg file. To install, double-click on it to mount it and then drag-and-drop the Gaia Sky.app application to your /Applications directory in Finder. Once copied, it is safe to unmount the dmg volume.

To run it, double-click on the Gaia Sky.app launcher in your applications directory.

In order to uninstall, quit Gaia Sky if it is running, and drag Gaia Sky.app from your /Applications directory to the trash.

Warning

Our macOS package is not signed by Apple, so it will be detected as coming from an ‘Unidentified Developer’. You can still install it by following the procedure described in this page.

TAR.GZ#

Download the package, and extract it wherever. Then, use either the gaiasky or gaiasky.cmd script to start the program. On a Unix system, do:

tar -xzvf gaiasky-$VERSION.tar.gz -C target/directory/
cd target/directory/gaiasky-$VERSION
./gaiasky

As with the AppImage, the TAR.GZ package is self-contained. To uninstall it, just delete the extracted folder.

First launch#

Hint

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

The first time you start Gaia Sky, you need the base data pack (key: default-data), which contains the Solar System, the Milky Way model, etc. Gaia Sky will offer to download it for you on the first launch. Catalogue 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 Dataset manager in the Data tab of the Preferences window. More information on the download manager can be found in Dataset manager.

You can also download the data packs manually here.

This applies to every installation method described above, including the packages, the AppImage and the TAR.GZ archive. You can configure Gaia Sky in the Preferences window (see Settings and configuration) or in the configuration file.

Run from source#

Requirements#

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

  • Java Development Kit (JDK). Gaia Sky is developed on the most recent version, so we recommend using at least the latest LTS.

  • Git.

Please be aware that only tags are guaranteed to work (here). The master branch holds the development version and the configuration files may not be properly configured and are 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 https://codeberg.org/gaiasky/gaiasky.git

Getting the catalog data#

Compiling and running#

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

./gradlew core:run

If you want to pass CLI arguments to the application, use the gradle --args argument:

./gradlew core:run --args='-vr'

Tip

Gaia Sky checks that your Java version is compatible with it when you run the build. Skip this check by setting the GS_JAVA_VERSION_CHECK environment variable to false in the context of gradle:

export GS_JAVA_VERSION_CHECK=false

In order to pull the latest changes from the remote git repository, use git pull in the repository folder.

Note

On Windows, open the Command Prompt or PowerShell in the repository folder and run .gradlew.bat core:run instead.

CLI arguments#

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

gaiasky -h

Usage: gaiasky [options] dataset

Options:
  -h, --help
    Show program options and usage information.
  -i, --ascii-art
    Add nice ascii art to --version information.
    Default: false
  -v, --version
    List Gaia Sky version and relevant 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, --openxr
    Launch in Virtual Reality mode. Gaia Sky will attempt to create a VR
    context through OpenXR. Make sure your OpenXR runtime is running.
    Default: false
  -e, --externalview
    Create a window with a view of the scene and no UI.
    Default: false
  -n, --no-script
    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
    logs.
    Default: false
  -g, --debug-gpu
    Activate OpenGL debug mode. Prints out debug information from OpenGL to
    the standard output.
    Default: false
  --debug-input
    Activate input debug mode. Prints out debug information for all input
    events (keyboard/mouse/controllers).
    Default: false
  -l, --headless
    Use headless (windowless) mode, for servers.
    Default: false
  --safe-mode
    Activate safe graphics mode. This forces the creation of an OpenGL 3.2
    context, and disables float buffers and tessellation.
    Default: false
  --no-safe-mode
    Force deactivation of safe graphics mode. Warning: this bypasses
    internal checks and may break things! Useful to get rid of safe graphics
    mode in the settings.
    Default: false
  --hdpi-mode
    The HDPI mode to use. Defines how HiDPI monitors are handled. Operating
    systems may have a per-monitor HiDPI scale setting. The operating system
    may report window width/height and mouse coordinates in a logical
    coordinate system at a lower resolution than the actual physical
    resolution. This setting allows you to specify whether you want to work
    in logical or raw pixel units.
    Default: Pixels
    Possible Values: [Logical, Pixels]

Packaging the software#

Gaia Sky can be exported to be run as a standalone app. Currently, this is only supported on Linux. You need the utility help2man in your path to generate the man pages. Remember to restart the gradle daemon after installing it. Then run:

./gradlew core:dist

This creates a new directory releases/gaiasky-$VERSION with the exported application. Run scripts are provided with the name gaiasky (Linux, macOS) and gaiasky.cmd (Windows).

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, just run:

./gradlew core:pack -PwinKeystorePassword=$PASSWORD

where $PASSWORD is the password of the certificate. This command produces the different OS packages (EXE, DMG, DEB, RPM, etc.) of Gaia Sky and stores them in the releases/packages-$VERSION directory.