Please be sure, to always use the latest version
Currently it is version 1.1.4
Prior versions will no longer be supported in special cases

Until this page is revised for version 1.1.4+ look here for
Getting Started


1.Check the prerequisites


-- Supported systems (generally 64-Bit only)


SikuliX can be used on systems with
  • Windows XP and later including Windows 8 and 10
  • Mac OSX 10.6 and later including 10.10+ (currently 10.13, my development system))
  • Linux/Unix systems depending on the availability of the prerequisites (look here for more information)
Mobile OS (like Android, iOS, ...) are currently NOT supported in native mode (VNC solutions might apply).

-- Valid Java installation


In any case you must have a valid Java installation of at least Java 8.
It is highly recommended, to always have a recent Oracle/Sun Java version on your system (version 8 recommended at least till end of 2018). For scripting and using the IDE a JRE pack is sufficient. If you are programming in Java you need the JDK pack. Equivalent versions of OpenJDK should work as well and in many cases are the only option on Linux systems.

Since after version 8 Oracle has changed the release concept. Now beginning in 2017 we will have a new major version every year (currently v10 and v11 in 2018). Probably every third release will be an LTS (Long Term Support). Currently this is version 8. Release 11 is expected to be the next LTS release (mid September 2018). Support for intermediate releases will be stopped with the next release (so now the end of support for version 10 will come soon). Beginning with version 11, there will not be functional differences between Oracle JDK and OpenJDK anymore. I will use the OpenJDK from now on, since it has an Open Source license.

So take care, that you either have the latest LTS release or the latest intermediate release.

— How to check your Java version
On a command line entering
java -version


-- Real Screen needed


The system running SikuliX scripts or any apps using SikuliX features must have a real screen connected. So called headless systems are not supported (Java restriction). While using SikuliX features, the screen should not be in sleep mode nor show a screen saver. It must be in a state, that a user could work with the system and watch on the screen what is going on.

-- Using Virtual Machines


Running it in VM guest systems as the above mentioned should usually work, but might have quirks.

-- Machine not useable in parallel while SikuliX scripts or programs are running


While running SikuliX scripts or any apps using SikuliX features on a system, usually one cannot work on this system in parallel, not even on another monitor, since normally SikuliX will "use" mouse and/or keyboard and watches the screen according to the running SikuliX workflow. User actions on this system will normally corrupt the SikuliX workflow, except this is intended and supported by the workflow.

— back to top —


2.How do I download SikuliX

valid for version 1.1.4 and later:

Download either the IDE or the API package, double-click it and start working.
For the API package you might add the dependency in your Maven or Gradle project as mentioned also on the download page.

valid until version 1.1.3:

Go to the download page and follow the instructions you find there.
After having completed the downloads come back here and continue with step 3.

BE AWARE: What you download is a sikulixsetup....jar, which is only intended to support setting up useable artifacts of SikuliX for your current system according to the selected setup options (see next section: How do I set up SikuliX).

The head of development might be available as a nightly build with bug fixes and enhancements.

— back to top —


3.How do I set up SikuliX

needed only until version 1.1.3:

After having downloaded sikulixsetup….jar you should consider the following recommendations, before doing anything:
  • select a prominent folder that is intended, to permanently contain all artifacts making up SikuliX
  • the path to this folder and its name should not contain any blanks or special characters (example: C:\SikuliX)
  • the folder should not be a program or application folder with special system access restrictions (must be freely user writeable)
  • into this folder copy/move sikulixsetup....jar
  • if this folder contains any content belonging to an earlier version of Sikuli(X), do some backup to be prepared to revert
  • to avoid odd situations you should always start with an empty folder (except sikulixsetup....jar and maybe a Downloads folder)
Again: take care, that you have a valid Java installation.

Double clicking sikulixsetup....jar should start the setup.

On Linux systems it might be necessary to switch on the executable bit in the file properties and you should have read this information.

If double-clicking does not work, you can try on a command line:
java -jar sikulixsetup....jar or
java -cp sikulixsetup....jar org.sikuli.setup.RunSetup


You have to at least select option 1 or 2 (the [ H ] buttons provide some more information) and you might select both.

— Option 1
will setup sikulix.jar, which contains the SikuliX IDE and can be used to run scripts from command line (see next section 4). As a sub-option you have to select the scripting languages you want to use
  • Python (Jython) (preselected) allows scripting using Python language level 2.7 (internally used interpreter Jython 2.7.1 )
  • Ruby: scripting using Ruby language level 1.9+ (internally used interpreter JRuby 1.9.x )

You might select both, since in the IDE you can select the scripting language per script.

On Mac you get a real Mac application SikuliX.app, that should be moved to the /Applications folder.

Additionally you get a command file runSikulix(.cmd) to run scripts from command line (see the docs).

— Option 2
will setup sikulixapi.jar, which is intended to be used with Java programming or programming with any Java aware language. It is much smaller, since it does not contain the IDE stuff nor the big packages for the scripting support (see section 8 below).

A Proxy might be specified for the internet access for the inline downloads during setup.

After having made your selections, click the button [Setup Now].

If everything works well, after successful internal download of the needed packages, you will get some intermediate yellow badges, hopefully positive popups from the tests and a final success message.

You might find the following files in your SikuliX setup folder:
  • SikuliX-x.y.z-SetupLog.txt --- contains debug information of setup workflow
  • sikulixsetup-x.y.z.jar (might have a lengthy version suffix)
  • runsikulix(.cmd) --- command script for commandline usages of SikuliX
  • sikulix.jar --- (non-Mac systems only) SikuliX IDE and scripting support (option 1)
  • SikuliX.app --- (Mac systems) Mac application, should be moved to /Applications (option 1)
  • sikulixapi.jar --- Java programming support (option2)

additionally you might have the optional folder
Downloads --- folder containing the manually downloaded artefacts

If you get any problems during setup, you should first have a look at the setup log file for any error messages or any information that helps to identify the cause of the problems.

If internal downloads are blocked on your system, you might try an Offline Setup.

If you want to repeat the setup for some reason
  • you should do some backup to be prepared to revert (existing files with the same name will be overwritten without notice)
  • setup will ask you to reuse already downloaded artefacts (say no if you want to download fresh copies)
  • Read carefully, what setup is asking you, before clicking anything!

Here you can read more about how SikuliX is setup on your system.

— back to top —


4.Getting started with SikuliX IDE


To start the SikuliX IDE, you have the following options:

  • start the respective application (on Mac: Sikulix.app, on Windows (if available): Sikulix.exe)
  • double click sikulix.jar (on Linux you might need to switch on the executable bit)
  • use runsikulix(.cmd) optionally with parameters on a command line
  • special on Mac commandline: open /Applications/SikuliX.app
  • use java -jar path-to-sikulix.jar optionally with parameters on a command line

— back to top —


5.How to run my scripts


Look here for more information.

— back to top —


6.How to deal with problems


Try to get help (see 7. Getting Help) or Switch on debugging

With an adequate debug level set, SikuliX might reveal more information on what is happening.

When running SikuliX IDE from command line (or a script) use as command line parameters
-d 3 sets the debug level to the recommended value.
-c will redirect the IDE output (normally shown in the IDE's message area) to the command line.

There is another special hack:
if you use the SikuliX apps or otherwise have no chance to set parameters:
before starting add an empty file named SikulixDebug.txt in your home folder.

This is detected and will internally switch to running with -d 3 -c and redirect all debug output to this file.
This is the only way to get debug output from the very beginning, when running SikuliX as .app on Mac or .exe on Windows.
Simply delete it, if it is not needed anymore, to get back to normal operation.

The debug level can also be set inline in scripts and code
... and will be used from this point on until switched off or reset to another value
  • Debug.on(3) — switch debugging on with level 3
  • Debug.off() — switch debugging off
Look here for more information about debugging and logging.

Post a bug
If you think, your problems are created by SikuliX malfunction in any way, you may post a bug on the SikuliX site on Launchpad.

For users of the SikuliX IDE:
Use the menu entry "Report a bug" in the Help menu, since it has special information, puts the version/system/java info to the clipboard, so it can be pasted and opens the Launchpad Bug site in your browser.

— back to top —


7.Getting help


You may ask questions and get answers from the SikuliX community and look at the FAQs on the SikuliX site on Launchpad.

For users of the SikuliX IDE:
Use the menu entry "Ask questions ..." in the Help menu, since it has special information, puts the version/system/java info to the clipboard, so it can be pasted and opens the Launchpad Question site in your browser.

The official SikuliX feature and API documentation is here.

JavaDocs can be found here (concentrating on the major public Java classes).

For special topics have a look at the Specials page

Still not found a suitable answers on your question: Many people ask on StackOverflow and get answers.

... and you might contact RaiMan directly.

— back to top —


8.Using Java and other IDE's


SikuliX Java API (sikulixapi.jar) is available for Maven(-aware) projects

Read here about HowTo's in Maven projects.

... more information on Usage in Java Programming

— back to top —