openMSX Launcher v1.14

openMSX Launcher is a front-end for openMSX written in Java, and runs on Windows, MacOS, Linux and BSD.

After starting the launcher for the first time, you need to set a few fields in the settings window.

First time installation

Windows: unzip the Windows package anywhere on your system.

MacOS: open the downloaded DMG and drag "openMSX" into your "Applications" directory.

Linux/BSD: unzip the Linux/BSD package anywhere on your system.

Upgrade from version 1.13

In all platforms (Windows, MacOS, Linux and BSD) you can upgrade from within the 'Help->Check for Updates' window. After you install, you need to restart the launcher.

Upgrade from versions earlier than 1.12

It is recommended that you upgrade to 1.13 first before upgrading to 1.14. You can find instructions on how to upgrade to 1.13 in the older 1.13 README file.

How to start

Windows: double-click on the exe file. The exe will locate the JRE on the machine automatically and start it. The exe takes in the JRE location as an optional argument in case it cannot find it. In this case, in order to pass the JRE location as an option, create a shortcut for the executable and edit its target to pass the JRE location. Make sure you add the location without double quotes (i.e. C:\Program Files\Java\jre1.8.0_212\bin\java.exe)

MacOS: double-click on the application icon.

Linux/OpenBSD: type and enter in a terminal window. In a GNOME environment you can create a shortcut to the launcher.


1) Emulator and machines directories:

Note: the detect button will 'suggest' the path to the openMSX based on the platform. Try that first, and if that doesn't work you can enter it manually.


Emulator: <Path>\


Emulator: /Applications

Linux (Debian, fedora, ubuntu):

Emulator: /usr/bin


Emulator: /usr/local/bin

2) Screenshots: This is the directory where game screenshots can be found. This collection of screenshots is the one used by blueMSX Launcher, and can be downloaded from:

3) Database: This is the database to display automatically when the launcher is started.

4) Language: openMSX Launcher supports many languages. When the launcher is started, it will try to detect the language of the system automatically. If that fails (i.e. if it still uses English text even if your system language is different), you can force the language selection here.

5) MSX News: This is to enable ot disable the MSX News service.

Fill Database

This is a tool that scans your storage drive for MSX software supported by openMSX and adds it to the launcher databases.

Change Machine

Here you can change machines in your launcher profiles in the current database or in all of them.


Favorites button is located above the four main buttons. When pressing it, a menu containing the currently saved favorites appears. You can go straight to your favorite game by selecting one from the list. You can also delete the favorite there as well.


Filters box can be found above the game list. When pressing the arrow on it, a menu pops up with a list of saved filters, small buttons to either delete or edit saved filters, quick filters and options to reset current filters and add new ones. When a filter is set but not saved, the filters box will be labeled (Untitled Filter). When hovering the mouse over the filters box in this state, a tooltip of the currently applied filters will appear.


Search button is located above the four main buttons. When pressing it, a text field appears. Enter any part of the name of the game or first few or all of SHA1 code. Search is case insensitive. SHA1 code search is useful if you want to locate a game by its SHA1 code to apply patches to it. As you type, a list of matches appears. Select the game you're looking for by mouse click or use arrow and enter keys to select it.

Note: mouse clicks don't work on Ubuntu (the only Linux flavour that was tested) or MacOS (Sierra). This could be a bug in the implementation that hasn't been identified yet. Use the Enter key instead.

MSX News

MSX News button is located above the four main buttons. The service must be enabled in the settings to retrieve the latest MSX news. When pressing the button, the latest news from MSX websites will be listed. The websites that are checked on a regular basis are:

MSX Launchers
MSX Resource Center
MSX Blog

Update All Databases

Note: starting from version 1.6 this feature is hidden by default. Check appendix A for details.
This is a tool that updates extra data for games in all databases (including update display of screenshots) when there's a new version of the extra-data.dat file and screenshots. It will also fix a bug that existed in versions 1.0 and 1.1 where some fields were not set correctly when using the 'Fill database' feature.

Right-click context menu

When right-clicking on one or more selected profiles in the games list, a context menu appears with the followig items:

1) Move: this allows you to move the selected profiles to other databases. A confirmation dialog with many options appears in case of conflicts.

2) Locate File: this only works on a single selection and it brings up the current platform's file manager. File Explorer on Windows and Finder on MacOS will open up with the profile's main file highlighted. On Linux running GNOME, nautilus will open up with the directory where game's main file is.

3) Add to Favorites: add the selected game to the list of favorites. The list is accessible through the favorites button in the main window.

4) Find Related: this finds up to 15 MSX games related to the currently selected game. The selection takes into account the game name, company and genre and the results are displayed with a screenshot for each, a link to the corresponding Generation-MSX page, a search link on YouTube and a link to the game in the launcher if one is found.

5) Info: this displays the user-specified info file using the system's default viewer. In the "Fill Database" feature, this field gets set to the game's MSX Generation page, but it can be anything the user desires (text file, PDF, etc).

6) Properties: this only works on a single selection and it brings up the properties screen for the selected game.

Database Manager

This can be accessed from the Tools menu and there you can rename or delete existing databases. You can also view, restore or delete backups. Backups are identified by their timestamps.

Activity Viewer

This can be accessed from the Tools menu and there you can view the game launch history as well as the most played 10 games.

IPS / UPS Patch Center

A tool to patch any files using IPS or UPS patches.

LHA Extractor

A tool to extract LHA/LZH files.

Drag and Drop

You can drag and drop game files and directories to the main launcher window for quick addition to the current database.

Keyboard short-cuts

Windows / Linux / BSDMacAction
DelDelRemove profile button
InsertInsertAdd profile button
Ctrl+ECommand+EEdit profile button
Ctrl+FCommand+FShow search field
Ctrl+DCommand+DAdd to favorites
Ctrl+QCommand+QShow list of databases
Ctrl+ICommand+IShow list of favorites
Ctrl+LCommand+LShow list of filters
Ctrl+RCommand+RReset filters
Ctrl+XCommand+XMove profile
F1F1Info button
Ctrl+Shift+FCommand+Shift+FLocate file
Ctrl+Shift+RCommand+Shift+RFind related games

Application menu on Ubuntu 15.10 and later

Starting from Ubuntu 15.10, Java Swing applications do not use Ubuntu's global menu and HUD by default even when this option is set in Ubuntu's settings for all applications. If you prefer to have openMSX Launcher menu behave the same as other applications, you can enable JAyatana (a project that integrates Java Swing applications with Ubuntu's global menu and HUD) globally by creating a file called "jayatana.conf" under /usr/share/upstart/sessions/ and pasting this in the file:
description "Java Ayatana"

start on starting dbus

 initctl set-env --global JAVA_TOOL_OPTIONS="-javaagent:/usr/share/java/jayatanaag.jar $JAVA_TOOL_OPTIONS"
end script

You can also enable it for only openMSX Launcher and not globally. You can find more information about this topic on the Web.

Support/Suggestions/Questions/Translation fixes/New translations

Email Sam Elsharif at oelsha at engineer dot com.

Release history

Version 1.14 - released June 1, 2020

Enhancements: Version 1.13 - released Mar 22, 2020

Enhancements: Version 1.12 - released Nov 3, 2019

Enhancements: Bug Fixes: Version 1.11 - released Aug 10, 2019

Enhancements: Version 1.10.6 - released Dec 16, 2018

Enhancements: Bug Fixes: Version 1.10.5 - released Mar 31, 2018

Enhancements: Version 1.10 - released November 11, 2017

Enhancements: Version 1.9 - released July 9, 2017

Enhancements: Version 1.8 - released Septebmer 12, 2016

Enhancements: Internal changes: Version 1.7 - released July 30, 2016

Enhancements: Bug fixes: Version 1.6 - released May 1, 2016

Enhancements: Bug fixes: Version 1.5 - released October 17, 2015

Enhancements: Bug fixes: Version 1.4 - released Feb 7, 2015

Enhancements: Bug fixes: Internal changes: Version 1.3 - released July 6, 2014

Enhancements: Bug fixes: Version 1.2 - released May 4, 2014

Enhancements: Bug fixes: Version 1.1 - released Sep 7, 2013

Enhancements: Bug fixes:

Version 1.0 - released Jul 8, 2013

Appendix A - Update all databases

This feature is disabled by default starting from version 1.6. It was needed everytime you made changes to the extra-data.dat file (this file contains SHA1 code mapping to MSX generation, sound chip and genre) to update internal launcher data. There are two ways to update the file: download it through the launcher upgrade or manually if there's a new version posted on the msxlaunchers website, or update it yourself to add your own dumps. It was deemed that the only common way to update the extra-data.dat file is through the launcher upgrade system, and through that method the internal data are updated automatically upon a successful download and upgrade. If you still need to update the databases manually, you can get the menu item to appear by adding the followng line to the launcher's settings-oml.ini file (location depends on platform):


and restart the launcher.