Install SystemDS from a Release
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