Installation Instructions

cholmcc · May 9, 2025, 7:11am

Installation instructions

Skip to

Windows
MacOS
Linux
ChromeBook
Android
SteamOS
Other

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

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

Head over to the VASSAL download page.
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
Download the installer, and remember where you downloaded it to (typically your Downloads folder).
Open your file manager (File Explorer) and navigate to where you downloaded the VASSAL installer.
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.

MacOS

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

Head over to the VASSAL download page
Download the disk-image (.dmg) for MacOSX, noting where you downloaded it to (typically your Downloads directory).
Open Finder and navigate to where you downloaded the image.
Double-click the installer and follow the on-screen instructions (i.e., drag the Vassal icon to the applications folder).

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.

The bundle in principle provides desktop integration, meaning Vassal files (.vmod, .vsav, .vlog, and .vmdx) are associated with the Vassal. However, due to a bug in OpenJDK, double clicking on a Vassal file does not automatically open that file in Vassal. One has to use the Vassal interface to open those files.

Linux

Debian and derivatives

For Debian GNU/Linux and derived Linux distributions - such as Kali, Knoppix, Mint, SteamOS, Ubuntu, Zorin, etc. - you can use the provided Debian package.

Head over to the Vassal download page and download the latest Debian package - file of the form vassal_<version>-1_all.deb from.
Open your file browser, and navigate to where you downloaded the file to - typically your ~/Downloads directory.
Double-click the downloaded file - vassal_<version>-1_all.deb - to install it. It will automatically download and install all needed packages from your distribution repository.

Alternatively, 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).

You can now execute Vassal from your system menu, or by running

$ vassal

This package will set up full desktop integration, meaning

Vassal files (.vmod, .vsav, .vlog, and .vmdx) 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.

Redhat and derivatives

For the Redhat and derived distributions, such as Fedora, CentOS, and many others, you can use the provided RPM package.

Point your browser to the Vassal download page and download the latest RPM - file of the form vassal-<version>-1.noarch.rpm.
Open your file browser, and navigate to where you downloaded the file to - typically your ~/Downloads directory.
Double-click the downloaded file - vassal-<version>-1.noarch.rpm - to install it. It will automatically download and install all needed packages from your distribution repository.

Alternatively, you can also do this from the terminal - assuming you downloaded vassal-3.7.21-1.noarch.rpm - by doing
```
$ cd ~/Downloads
$ sudo dnf install vassal-3.7.21-1.noarch.rpm
```
(replace the version number with the version you downloaded).

If your distribution uses yum instead of dnf, do
```
$ cd ~/Downloads
$ sudo yum install vassal-3.7.21-1.noarch.rpm
```
(replace the version number with the version you downloaded).

You can now execute Vassal from your system menu, or by running

$ vassal

This package will set up almost full desktop integration, meaning

Vassal files (.vmod, .vsav, .vlog, and .vmdx) 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.

FlatPak

To use a FlatPak installation of Vassal, you can download the latest FlatPak package. First, however, you need to make sure you have FlatPak installed.

Install FlatPak
- If you generally use a graphical user interface to install packages - such as GNOME Software or KDE Discover fire that up and search for FlatPak, or some FlatPak manager like Bazaar, and install an appropriate package.
- On Debian and derived distributions, do one of
```
$ sudo apt install flatpak
$ sudo apt install bazaar
```
- On RedHat and derived distributions, do one of
```
$ sudo dnf install flatpak
$ sudo yum install flatpak
```
  After you’ve installed flatpak, you can install Bazaar with
```
sudo flatpak install io.github.kolunmi.Bazaar
```
Install the latest org.vassalengine.vassal package from flathub.
- If you use the command line interface, flatpak, do
```
$ sudo flatpak install org.vassalengine.vassal 
```
- If you use a graphical user interface, such as Bazaar, search for org.vassalengine.vassal and use the interface to install the package.

You can now execute Vassal as one of

$ flatpak run org.vassalengine.vassal
$ VASSAL.sh
$ vassal

This package will set up almost full desktop integration, meaning

Vassal files (.vmod, .vsav, .vlog, and .vmdx) 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.

Generic Linux

If you are not using Debian GNU/Linux or RedHat, or one of their many derivatives, and do not want to use FlatPak, 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.

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.

If you generally use a graphical user interface to install packages - such as GNOME Software or KDE Discover fire that up and search for Java, JRE, or JDK, and install an appropriate package.

For specific distributions using, the command line, follow the below instructions.

Install a JRE on 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
Install a JRE on 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.
Install a JRE on 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.
Install a JRE on 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.
Install a JRE on Other distributions

Please refer to your distribution’s documentation.

Download Vassal for Generic Linux

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

Install Vassal on Generic Linux

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 as a system-wide installation.

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.

System-wide

Make sure the directory /opt/vassal exists.
```
$ sudo mkdir -p /opt/vassal
```
Change directory to /opt/vassal
```
cd /opt/vassal
```
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 for 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).
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

Single-user

Make sure the directory ~/Vassal exists.
```
$ mkdir -p ~/Vassal
```
Change directory to ~/Vassal
```
cd ~/Vassal
```
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 for 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).
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 integration

As of version 3.7.21 of Vassal, the generic Linux package now ships with all the tools you need to set-up the desktop integration. For older releases of Vassal, the article How to Integrate VASSAL into the Linux Desktop.

To set it up, do

Change directory to where you installed Vassal, say /opt/vassal/current or ~/Vassal/current.
Run the script integration.sh you find there.
- If you want the integration system-wide, do
```
 $ sudo sh ./integration.sh --system -v /opt/vassal/current
```
- If you want the integration only for the current user, do
```
$ sh ./integration.sh --user -v ~/Vassal/current
```

If you follow the recommendations above and place Vassal in /opt/vassal/<version> and have a symbolic link from /opt/vassal/current to there, then this only needs to be done once.

To remove the system integration, do the following steps

Change directory to where you installed Vassal, say /opt/vassal/current or ~/Vassal/current.
Run the script integration.sh - with the option --remove - you find there.
- If you want to remove the system-wide integration, do
```
 $ sudo sh ./integration.sh --system --remove
```
- If you want to remove the integration for the current user, do
```
$ ./integration.sh --user --remove
```

ChromeBook

ChromeBooks (or ChromiumBook) 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

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

SteamOS

Please see the article How to Run VASSAL on SteamDeck

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

First, check the Documentation index, in particular known issues, to see if your problem has a known solution.
Secondly, check the forum, in particular the Technical Support & Bugs category, if your problem has already been solved.
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.