Installation Instructions

Documentation
1

Installation instructions

VASSAL is a Java application, which allows it to run on any platform that can run the Java platform - or Java Runtime Environment (JRE). This encompasses most desktop platforms, such as Windows, MacOSX, and Linux, as well as other systems such as FreeBSD, Solaris, and so on. It is even possible to run a fully-fledged JRE on Android (but not iOS).

windows Windows

The VASSAL installer for Windows comes with a JRE, and there’s no need install Java separately.

  1. Head over to the VASSAL download page
  2. Select the installer file for your architecture
    • .exe for 64-bit x86 - this is most likely what you want.
    • .exe for 32-bit x86 - for older machines.
    • .exe for 64-bit ARM - for more specialised machines
      If in doubt, check out the MicroSoft FAQ
  3. Download the installer, and remember where you downloaded it to (typically your Downloads folder)
  4. Open your file manager (File Explorer) and navigate to where you downloaded the VASSAL installer.
  5. Double-click the installer and follow the on-screen instructions.

If you have trouble installing, check Issues with Download, Installation or Running being Blocked to see if there is a known solution.

macosx MacOSX

The VASSAL disk-image for MacOSX comes with a JRE, and there’s no need install Java separately.

  1. Head over to the VASSAL download page
  2. Download the disk-image (.dmg) for MacOSX, noting where you downloaded it to (typically your Downloads directory).
  3. Open Finder and navigate to where you downloaded the image.
  4. Double-click the installer and follow the on-screen instructions.

If you have trouble installing, check Issues with Download, Installation or Running being
Blocked to see if there is a known solution.

For installation on older MacOSX versions (MacOS 10.13 or older), check if the post Installing Vassal for older MacOS machines works for you.

linux Linux

The below assumes a bit of familiarity with the command line - see also here. Alternatively, you can use your distributions graphical user interface (GUI) tools for package installation, archive expansion, etc.. Please refer to your distributions documentation.

The VASSAL application for Linux does not come with JRE, and you therefore need to install JRE first.

java Install the JRE

Please make sure you get at least the required version of JRE (see the note on the VASSAL download page). As of this writing (Spring of 2025) you need at least version 11.

debian Debian and derivatives

For the Debian GNU/Linux and derived distributions, such as Ubuntu, Mint, Kali, and many many others, package installation is done via apt. To install a JRE, do

$ sudo apt install default-jre

Consult your distribution documentation on Java, e.g., Debian’s or Ubuntu’s, for more information and trouble-shooting

redhat Redhat and derivatives

For the Redhat and derived distributions, such as Fedora, CentOS, and many others, package installation is done via dnf. To install a JRE, do

$ sudo  dnf install java-latest-openjdk

Some Redhat derivatives may use yum rather than dnf. For those distributions, do

$ sudo yum install java-latest-openjdk

Consult your distribution documentation on Java, e.g., Fedora’s, RHEL’s, for more information and trouble-shooting.

arch Arch Linux and derivatives

For Arch Linux and derived distributions, such as Manjaro, and SteamOS, package installation is handled by the pacman. To install a JRE, do

$ sudo pacman -S --needed jre-openjdk

See also ArchLinux Java documentation.

gentoo Gentoo and derivatives

For Gentoo and derived distributions, such as ChromeOS, and ChromiumOS, package installation is handled by the portage system. To install a JRE, do

$ sudo emerge --ask --oneshot virtual/jre

See also Gentoo’s Java documentation.

other Other distributions

Please refer to your distribution’s documentation.

vassal Download VASSAL

  1. Head over to the VASSAL download page
  2. Download the compressed tar-ball .tar.bz2 for all architectures, noting where you downloaded the file (typically your Downloads - or ~/Downloads directory)

vassal Install VASSAL

When installing VASSAL you have choice of where to put it, and how to install it. Common destinations are

  • /opt/vassal for system-wide installation
  • ~/Vassal for single-user installations

It is recommended to install in /opt/vassal

Furthermore, you may want to do a flexible installation that allows you to quickly and easily change the VASSAL version you are running.

However, you are free to do the installation in anyway you want.

global System-wide

  1. Make sure the directory /opt/vassal exists.

    $ sudo mkdir -p /opt/vassal

  2. Change directory to /opt/vassal

    cd /opt/vassal

  3. Unpack the downloaded compressed tar-ball to that directory. Assuming the tar-ball was downloaded into ~/Downloads/VASSAL-3.7.16-linux.tar.bz2 (adjust of actual download directory and VASSAL version number), do

    $ sudo tar -xjf ~/Downloads/VASSAL-3.7.16-linux.tar.bz2

    This will create the directory VASSAL-3.7.16 (adjust for actual version number).

  4. Make a symbolic link from the unpacked directory to current

    $ sudo ln -s VASSAL-3.7.16 current

    (adjust for actual version number).

    This step is optional, but recommended.

    This will make it so that /opt/vassal/current points to the installed version of VASSAL. Should you later want to use a different version, then download the tar-ball and unpack as detailed in 3 above. Then, remove the old link and make a new one from the new installation. Say you got 3.7.20, then do

    $ cd /opt/vassal
$ sudo rm current 
$ sudo ln -s VASSAL-3.7.20 current

You can now execute VASSAL by running

/opt/vassal/current/VASSAL.sh

home Single-user

  1. Make sure the directory ~/Vassal exists.

    $ mkdir -p ~/Vassal

  2. Change directory to ~/Vassal

    cd ~/Vassal

  3. Unpack the downloaded compressed tar-ball to that directory. Assuming the tar-ball was downloaded into ~/Downloads/VASSAL-3.7.16-linux.tar.bz2 (adjust of actual download directory and VASSAL version number), do

    $ tar -xjf ~/Downloads/VASSAL-3.7.16-linux.tar.bz2

    This will create the directory VASSAL-3.7.16 (adjust for actual version number).

  4. Make a symbolic link from the unpacked directory to current

    $ ln -s VASSAL-3.7.16 current

    (adjust for actual version number).

    This step is optional, but recommended.

    This will make it so that ~/Vassal/current points to the installed version of VASSAL. Should you later want to use a different version, then download the tar-ball and unpack as detailed in 3 above. Then, remove the old link and make a new one from the new installation. Say you got 3.7.20, then do

    $ cd ~/Vassal
$ rm current 
$ ln -s VASSAL-3.7.20 current

You can now execute VASSAL by running

~/Vassal/current/VASSAL.sh

desktop Desktop integration

Please see the article How to Integrate VASSAL into the Linux Desktop.

chromeos ChromeBook

ChromeBooks (or ChromioumBook) are running the Linux kernel with a Graphical User Interface based on the Chrome (or Chromium) browser. As such, it is just another Linux machine.

You need to turn on “Linux” by following these instructions.

Note, this is such a misleading way of talking about this. What you really are doing is simply to enable particular interfaces which are already present on your system: ChromeOS is already running the Linux kernel and all the command-line tools are already there - they are just not visible to you: A case of Security-by-Obscurity.

Follow the instructions for Linux, in particular the Debian GNU/Linux instructions for installing the Java Runtime Environment.

android Android

Please see the article How to Run VASSAL on Android (X11)

steamos SteamOS

Please see the article How to Run VASSAL on SteamDeck

other Other platforms

For all other platforms, you will need to get a JRE on the machine. Please refer to your platform’s documentation.

Please make sure you get at least the required version of JRE (see the note on the VASSAL download page). As of this writing (Spring of 2025) you need at least version 11.

Other steps will then follow the same procedure as for Linux.

Trouble shooting

  1. First, check the Documentation index, in particular known issues, to see if your problem has a known solution.

  2. Secondly, check the forum, in particular the Technical Support & Bugs category, if your problem has already been solved.

  3. If your problem persists, create a new post in the Technical Support & Bugs, following these guidelines and taking care to format your message for readability

    Hopefully, someone will have a solution to your problem quickly.