Installation Instructions

Documentation
1

Installation instructions

Skip to

Introduction

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.

debian Debian and derivatives

For Debian GNU/Linux and derived Linux distributions - such as Kali, Knoppix, Kali, Mint, SteamOS, Ubuntu, Zorin, etc. - you can download the latest Debian package - file of the form vassal-<version>-1_all.deb from GitHub releases page (as of this writing, no link is provided from the Vassal download page.

Typically, the download will end up in your Downloads folder. Open that folder with your file browser and double-click the file to install it. It should automatically download and install all needed packages from your distribution repository.

You can also do this from the terminal - assuming you downloaded vassal-3.7.19-1_all.deb - by doing

$ cd ~/Downloads
$ sudo apt install ./vassal-3.7.19-1_all.deb

(replace the version number with the version you downloaded).

This package will set up full desktop integration, meaning

  • Vassal files (.vmod, .vsav, .vlog, and .vext) are associated with Vassal and you can simply double-click such a file to open it in Vassal.
  • Vassal is registered as a (Game) application with system menus and so on.
  • Documentation is integrated in to the systems documentation repository.
  • The Vassal API JAR Vengine.jar is placed in a predictable location (/usr/share/java)
  • The package uses already available third-party JARs and thus benefits from (security) updates to those third-party packages.

linux Generic Linux

If you are not using Debian GNU/Linux, or one of its many derivatives, you must install Vassal “by-hand”.

Vassal for Linux consists of a Java Archive (JAR), some auxiliary files, and a wrapper script to execute the JAR. It does not come with a JRE, and one must therefore be installed 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 Vassal.

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.