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 MacOS

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 (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.

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 use the provided Debian package.

  1. Head over to the GitHub releases page and download the latest Debian package - file of the form vassal_<version>-1_all.deb from (as of this writing, no link is provided from the Vassal download page).

  2. Open your file browser, and navigate to where you downloaded the file to - typically your ~/Downloads directory.

  3. 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 .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.

redhat Redhat and derivatives

To come. For now, use the Generic Linux instructions

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

  1. Point your browser to the GitHub releases page and download the latest RPM - file of the form vassal-<version>-1.noarch.rpm (as of this writing, no link is provided from the Vassal download page).

  2. Open your file browser, and navigate to where you downloaded the file to - typically your ~/Downloads directory.

  3. 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 .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.

flatpak FlatPak

To come. For now, use the Generic Linux instructions

To use a FlatPak installation of Vassal, you can download the latest FlatPak recipe.

  1. Head over to the GitHub releases page and download the latest FlatPak recipe - file of the form VASSAL-<version>-flatpak.yaml (as of this writing, no link is provided from the Vassal download page).

  2. Then, you need to make sure you have the latest freedesktop Platform, SDK, and Sdk.Extension.openjdk25 frameworks installed

    $ sudo flatpak install org.freedesktop.Platform
$ sudo flatpak install org.freedesktop.Sdk
$ sudo flatpak install org.freedesktop.Sdk.Extension.openjdk25

    Make sure you choose the latest available version when prompted to.

  3. Now navigate to where you downloaded the recipe file - say VASSAL-3.7.21-flatpak.yaml - which is typically ~/Downloads

     $ cd ~/Downloads

    and build and install the Vassal package, assuming the recipe downloaded

    sudo flatpak-builder --install build  `VASSAL-3.7.21-flatpak.yaml`

    (adjust for actual version number downloaded).

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 .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.

linux 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.

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.

vassal Download Vassal for Generic Linux

  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 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

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 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.

  1. 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.

  2. 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

  1. 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.

  2. 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.

Problem with file dialog
How do I start vassal in Linux?
Vassal 3.7.20 Released
Vassal 3.7.20 Released
Problem with file dialog