layout: site title: Install SystemDS from a Release description: Installation guide for SystemDS using release archives

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

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:

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 systemdsCLI wrapper may not be executable. This is expected because the bin/systemdslauncher 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:

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:

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:

Get-Content .\hello.dml

Expected output:

print("Hello World!")

2.4 Run the Script

Now run the script:

java -jar systemds-3.3.0.jar -f .\hello.dml

Expected output:

Hello World!
SystemDS Statistics:
Total execution time: 0.012 sec.

3. Install on Ubuntu

3.1 Extract the Release

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.

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:

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):

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

systemds -help

You should see usage information printed to the console.

3.4 Create a Simple Script

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:

systemds -f hello.dml

Expected output:

Hello World!

4. Install on MacOS

4.1 Extract the Release

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

4.2 Add SystemDS to PATH

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):

export SYSTEMDS_ROOT=/absolute/path/to/systemds-<VERSION>
export PATH=$SYSTEMDS_ROOT/bin:$PATH

4.3 Verify the Installation by Checking the CLI

systemds -help

You should see usage information printed to the console.

4.4 Create a Simple Script

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

4.5 Run the Script

systemds -f hello.dml

Expected output:

Hello World!

Next Steps

For running scripts in Spark mode or experimenting with federated workers, see the Execution Guide: Execute SystemDS