webMathematica requires that Java, a Servlet container and Mathematica are installed on the system. Certain functionality in Mathematica, and hence webMathematica, requires the use of Mathematica's front end. The front end, in turn, requires an X Window System on Linux. The steps to install webMathematica are as follows:

  1. Setting Up Java
  2. Setting Up Tomcat
  3. Setting Up Mathematica
  4. Making Licensing Files Accessible to the “Tomcat” User
  5. Installing and Setting Up webMathematica
  6. Configuring Xvnc for Minimal or Server Editions of Linux


Setting Up Java

Java is required not only for webMathematica but also for any Java Servlet container. You can access Oracle’s Java from http://www.oracle.com/us/downloads/index.html.

In several Linux distributions, Java packages can also be installed via either the command line or through their software centers:


sudo yum install java-1.8.0-openjdk
sudo yum install java-1.8.0-openjdk-devel 


sudo apt install openjdk-8-jre
sudo apt install openjdk-8-jdk

To verify the successful installation, on the command line, execute:

java -version



Setting Up Tomcat


webMathematica is designed to operate from within a Java Servlet container. Among various available Servlet containers, we provide limited guidance with Apache Tomcat only.

  1. Go to http://tomcat.apache.org/download-80.cgi.
  2. Download the installer in the format of tar.gz.
  3. In the location you wish to install the server, execute:
    sudo tar -xvzf apache-tomcat-<version>.tar.gz

Creating a Tomcat Account

It is recommended that you set up a separate account to run the server under, which we name “tomcat”. This account needs the permissions to run webMathematica.

  1. To create the account, execute in the terminal:
    sudo useradd tomcat
    sudo passwd tomcat

  2. Change the ownership and group of the Tomcat installation directory to the “tomcat” user by executing these commands from the parent directory where you installed the apache-tomcat server:
    sudo chown -R tomcat apache-tomcat-<version>
    sudo chgrp -R tomcat apache-tomcat-<version>

Testing Tomcat

  1. To start the Tomcat server, in the Tomcat installation directory, execute:


Common possible issues:

  • The computer’s firewall is blocking requests to Tomcat. Tomcat, by default, runs on port 8080. Ensure that the port is open to accept tcp packets on the system running the tomcat server.
  • If you downloaded Java from Oracle’s website, the Tomcat server may not be able to find the Java installation. In such a case, set the system variable JAVA_HOME to Java’s installation directory, e.g. by executing the following on a bash command line or by adding these lines to .bashrc, if your Java was installed in /usr/local/jdk1.8.0.
    export JAVA_HOME

Setting Up Mathematica

Setting up Mathematica requires installing the program, activating it with your activation key and moving the generated licensing information into a location that makes it accessible globally on the machine in question.


Follow the instructions for installing Mathematica on Mac.

Ensure you use the appropriate file name:

sudo sh Mathematica_12.x_LINUX.sh

Take note of the installation directory you choose if you do not use the default.


Activate Mathematica using online or manual activation.

On Linux systems without X Window installed, the Mathematica front end will not be available. Instead, activate Mathematica through the kernel.

  1. Execute the following command:

  2. Enter your activation key. Note the activation key has the form XXXX-XXXX-XXXXXX.

Making Licensing Files Accessible to the “Tomcat” User



  2. To identify the base directory location, evaluate:

    For example:

    Mathematica 12.x.x Kernel for Linux x86 (64-bit)
    Copyright 1988-2019 Wolfram Research, Inc.
    In[1]:= $PasswordFile                                                          
    Out[1]= /home/user/.Mathematica/Licensing/mathpass
    In[2]:= $BaseDirectory                                                          
    Out[2]= /usr/share/Mathematica

These folder locations are used in the following instructions.

  1. The Licensing directory may not yet exist. If so, create it by executing the following command:
    sudo mkdir -p /usr/share/Mathematica/Licensing

  2. Copy the mathpass file to the Licensing directory of the base directory:
    sudo cp /home/user/.Mathematica/Licensing/mathpass /usr/share/Mathematica/

  3. Grant read access to the mathpass file for all accounts:
    sudo chmod a+r /usr/share/Mathematica/Licensing/mathpass

Installing and Setting Up webMathematica


webMathematica's installation files contain webMathematica.zip. Place it into the webapps directory of your Apache Tomcat servers and unzip the file to ensure it is opened and unpacked at startup. Assuming that you have defined $TOMCAT_INSTALL to represent the installation directory of your Tomcat server, evaluate the following:

  1. sudo mv webMathematica $TOMCAT_INSTALL/webapps/

  2. sudo chown -R tomcat $TOMCAT_INSTALL/webapps/webMathematica

  3. sudo chgrp -R tomcat $TOMCAT_INSTALL/webapps/webMathematica

  4. su tomcat

  5. ./$TOMCAT_INSTALL/bin/shutdown.sh

  6. ./$TOMCAT_INSTALL/bin/startup.sh

Testing and Troubleshooting

The webMathematica package comes with some default pages that can be used to test the setup of webMathematica.

  1. Access the base page by pointing a browser to “localhost:8080/webMathematica”.

  2. As a first test, click the Hello World example. The Hello World page providing the current time and date appears.

  3. If Hello World is not working, check the log file by executing:
    less $TOMCAT_INSTALL/logs/webMathematica.log

Common possible issue:

Search the above log file for error ....com.wolfram.kerneltools.state.StateMachine [ERROR] Could not find MathLink executable. In such a case, webMathematica could not find the executable of the Mathematica kernel. This can occur if you have installed Mathematica in a non-standard location or if a version of webMathematica is not paired with the recommended Mathematica version, e.g. webMathematica 3.5 was released for Mathematica 12.0 and looks in the default installation directory of Mathematica for the executable.


  1. On the command line, go to $TOMCAT_INSTALL/webapps/webMathematica/WEB-INF/ and locate the file MSPConfiguration.xml.
  2. Open MSPConfiguration.xml in a text editor and locate the following section:
  3. <KernelPool>

  4. Edit and change this section to:

  5. Note: These instructions assume Mathematica 12.x was installed to
    /usr/local/Mathematica/12.x/. If you have a different installation directory, substitute the
    installation directory you used.

Configuring Xvnc for Minimal or Server Editions
of Linux

Many “Server” or “Minimal” distributions of Linux do not include an X Window server by default. Some Mathematica functionality and thus some webMathematica functionality requires an X Window server to be available. For instance, the Plot Example cannot execute properly without an X Window system of some sort. For these purposes, it is recommended that you run an Xvnc server.

  1. Install an Xvnc server, which can commonly be obtained through command line install applications like yum or apt.
  2. Launch a vnc display with the command “vncserver”. This will initially require you to provide a display number (typically 1).
  3. Configure webMathematica to use the display by editing the file $TOMCAT_INSTALL/webapps/webMathematica/WEB-INF/MSPConfiguration.xml to include the following code:
    -display :1 -nogui 1000x500+10+10