Getting Started

Install XEarthLayer and start flying with photoreal scenery in X-Plane 12.

This guide will help you install XEarthLayer and get flying with photoreal scenery in minutes.

Prerequisites

  • X-Plane 12 installed on your system
  • Linux (Debian/Ubuntu, Fedora/RHEL, or Arch Linux) with FUSE support
  • At least 2GB free RAM for the memory cache
  • Internet connection for streaming imagery
X-Plane 12.1.1 or later is recommended. XEarthLayer connects to X-Plane automatically via the Web API (enabled by default since 12.1.1) to read aircraft position, heading, and speed. This powers adaptive prefetching so tiles are ready before you need them. If X-Plane is not running when XEarthLayer starts, it falls back to inferring position from file access patterns.

Installation

git clone https://github.com/samsoir/xearthlayer.git && cd xearthlayer && make install

Initial Setup

  1. Run the setup wizard (recommended for first-time users):

    xearthlayer setup

    The wizard will guide you through:

    • Detecting your X-Plane 12 installation
    • Choosing package and cache locations
    • Configuring optimal settings for your hardware

  2. Install a regional scenery package:

    List available regional scenery packages:

    xearthlayer packages check

    Install a package (e.g., Europe):

    xearthlayer packages install EU

    Or North America:

    xearthlayer packages install NA

  3. Start XEarthLayer:

    xearthlayer

    This defaults to the run command. You can also use xearthlayer run explicitly. Leave this terminal running while you fly in X-Plane.

  4. Launch X-Plane and fly! You should see satellite imagery streaming in as you move around.

Stopping the Service

When you are done flying, close X-Plane first. Then stop XEarthLayer cleanly by pressing the q key in the terminal and following the prompt to confirm.

Always stop XEarthLayer cleanly before shutting down. Terminating the process while X-Plane is still running will cause X-Plane to crash to desktop.

Verifying It Works

When XEarthLayer is running, you’ll see a real-time dashboard showing:

  • Cache statistics (memory and disk usage)
  • Download activity (tiles being fetched)
  • Aircraft position (when connected to X-Plane via the Web API)
  • Pipeline health (download, assembly, encode stages)

If you see tiles being downloaded and cache hits increasing, XEarthLayer is working correctly.

Next Steps