docs/site/release_install.md

---
layout: site
title: Install SystemDS from a Release
description: Installation guide for SystemDS using release archives
---
<!--
{% comment %}
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements.  See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to you under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License.  You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
{% endcomment %}
-->

This guide explains how to install and set up SystemDS using the pre-built release archives. 

---

- [1. Download a Release](#1-download-a-release)
- [2. Install on Windows](#2-install-on-windows)
- [3. Install on Ubuntu 22.04](#3-install-on-ubuntu-2204)
- [4. Install on MacOS](#4-install-on-macos)

---

# 1. Download a Release

Download the official release archive from the Apache SystemDS website:

<https://systemds.apache.org/download/>

After downloading the file `systemds-<VERSION>.tar.gz`, place the file in any directory you choose for installation.

### Java Requirement ###
For compatability with Spark execution and parser components, **Java 17** is strongly recommended for SystemDS.

Verify Java 17:

```bash
java -version
```

If missing, install a JDK 17 distribution.

---

# 2. Install on Windows

### 2.1 Extract the Release Archive

Use Windows built-in extractor.

### 2.2 Verify the Installation by Checking the CLI

On Windows, the `systemds`CLI wrapper may not be executable. This is expected because the `bin/systemds`launcher is implemented as a shell script, which Windows cannot execute natively. To verify the installation on Windows, navigate to the bin directory and run the JAR directly. Note that running `systemds -help` without JAR may result in a CommandNotFoundExeption:

```ps1
java -jar systemds-<VERSION>.jar -help
```

You should see usage information as an output printed to the console.

### 2.3 Create a Simple Script

On Windows, especially when using PowerShell, creating text files via shell redirection (e.g., echo...) may result in unexpected encoding or invisible characters. This can lead to parsing errors when executing the script, even though the file appears correct in an editor. Therefore, you may try creating the file explicitly using PowerShell:
```ps1
Set-Content -Path .\hello.dml -Value 'print("Hello World!")' -Encoding Ascii
```

This ensures the script is stored as plain text without additional encoding metadata.
Note: This behavior depends on the shell and environment configuration and may not affect all Windows setups.

Verify the file contents:
```ps1
Get-Content .\hello.dml
```

Expected output:
```ps1
print("Hello World!")
```

### 2.4 Run the Script

Now run the script:
```ps1
java -jar systemds-3.3.0.jar -f .\hello.dml
```

Expected output:
```ps1
Hello World!
SystemDS Statistics:
Total execution time: 0.012 sec.
```

# 3. Install on Ubuntu

### 3.1 Extract the Release

```bash
cd /path/to/install
tar -xvf systemds-<VERSION>-bin.tgz
cd systemds-<VERSION>-bin
```

### 3.2 Configure Environment Variables

The SystemDS CLI requires an environment variable pointing to the SystemDS JAR. Make sure to export both `SYSTEMDS_ROOT` and `SYSTEMDS_JAR_FILE`.

```bash
export SYSTEMDS_ROOT=$(pwd)
export SYSTEMDS_JAR_FILE=$(find "$SYSTEMDS_ROOT" -maxdepth 1 -type f -name "systemds-*.jar" | head -n 1)
export PATH="$SYSTEMDS_ROOT/bin:$PATH"
```

Verify that the JAR was found correctly:
```bash
echo "Using SystemDS JAR: $SYSTEMDS_JAR_FILE"
```

(Optional but recommended) To make SystemDS available in new terminals, add the following lines to your shell configuration (e.g., `~/.bashrc` or `~/.profile`):
```bash
export SYSTEMDS_ROOT=/absolute/path/to/systemds-<VERSION>
export SYSTEMDS_JAR_FILE=/absolute/path/to/systemds-<VERSION>-bin/lib/systemds-<VERSION>.jar
export PATH="$SYSTEMDS_ROOT/bin:$PATH"
```

### 3.3 Verify the Installation by Checking the CLI

```bash
systemds -help
```

You should see usage information printed to the console.

### 3.4 Create a Simple Script

```bash
echo 'print("Hello World!")' > hello.dml
```

### 3.5 Run the Script

With `SYSTEMDS_JAR_FILE` properly set, the script can be executed directly via the CLI:
```bash
systemds -f hello.dml
```

Expected output:
```bash
Hello World!
```

# 4. Install on MacOS

### 4.1 Extract the Release

```bash
cd /path/to/install
tar -xvf systemds-<VERSION>-bin.tgz
cd systemds-<VERSION>-bin
```
### 4.2 Add SystemDS to PATH

```bash
export SYSTEMDS_ROOT=$(pwd)
export PATH="$SYSTEMDS_ROOT/bin:$PATH"
```

(Optional but recommended)
To make SystemDS available in new terminals, add the following lines
to your shell configuration (e.g., ~/.bashrc or ~/.profile):
```bash
export SYSTEMDS_ROOT=/absolute/path/to/systemds-<VERSION>
export PATH=$SYSTEMDS_ROOT/bin:$PATH
```

### 4.3 Verify the Installation by Checking the CLI

```bash
systemds -help
```

You should see usage information printed to the console.

### 4.4 Create a Simple Script

```bash
echo 'print("Hello World!")' > hello.dml
```

### 4.5 Run the Script

```bash
systemds -f hello.dml
```

Expected output:

```bash
Hello World!
```

# Next Steps

For running scripts in Spark mode or experimenting with federated workers, see the Execution Guide: [Execute SystemDS](run)