Wiki Spaces


Get Help from Others

Q&A: Ask OpenMRS
Discussion: OpenMRS Talk
Real-Time: IRC Chat | Slack


Page tree
Skip to end of metadata
Go to start of metadata

Why Are You Here?

You are probably seeing this page because you installed the OpenMRS Platform, and saw a nearly-empty screen that linked you here, instead of the EMR you were expecting to see.

Starting with version 2.0 the OpenMRS Platform does not include a built-in user interface. The rationale is that this will enable people to build all sorts of different OpenMRS distributions, using completely different web technologies to build different user interfaces. However, this can be confusing if you installed the raw OpenMRS Platform, but you were looking for a full OpenMRS Distribution (like the Reference Application).

What Can You Do?

If you are a "typical" OpenMRS user and you are looking for a complete OpenMRS application, you probably want to remove this installation, and replace it with one of the out-of-the-box OpenMRS Distributions (like the Reference Application).

If you're sure that you want this version of the OpenMRS Platform, and you want to add a community-supported user interface on top of it, you have a couple of options:

Installing the Reference Application

If you are already running the OpenMRS Platform, then you need to add quite a few modules to be running the full Reference Application. You can get these by going to and looking for a link like "Download Reference Application (version number) Addons". (Make sure to get the version of the reference application that corresponds to the platform version that you are running. Unzip that file, and put all the OMOD files in your modules folder(e.g. ${HOME}/.OpenMRS/modules) or (Windows + R > %appdata%>OpenMRS>Modules), and all the OWA files in your owa folder, and restart the web server.

Installing the Legacy UI module

For Implementers

  1. Get the latest version of the legacyui module from the OpenMRS Module Repository
    Go to and download the latest version. 

  2. Install the module
    After the download completes, copy the .omod file (legacyui-{versionNumber}.omod) into the modules directory of your OpenMRS app data folder (e.g. ${HOME}/.OpenMRS/modules) or (Windows + R > %appdata%>OpenMRS>Modules).
  3. Restart OpenMRS
    You can do this by either stopping and starting openmrs from tomcat manager page or just restarting tomcat.

For Developers

  1. Get the latest version of the legacyui module code

    git clone
  2. Build the module

    cd openmrs-module-legacyui
    mvn clean install
  3. Install the module
    After successfully building the legacyui module, you will find it at openmrs-module-legacyui/omod/target/legacyui-{version}-SNAPSHOT.omod.
    Take this file and install it, as described in the For Implementers section.
  4. Restart OpenMRS
    If you are running jetty in a typical dev environment setup, then kill the already running instance of jetty (CTRL + C) and then run "mvn jetty:run" again.


  1. If after following the instructions for installing the legacyui with no success. Please leave a comment. The instructions for reference application module are still on the way (smile)

  2. I've been able to successfully build the Legacy UI module, but I've not been able to locate the proper directory to copy it to in the build of openmrs-core.   I've tried copying the LegacyUI omod file to


    However, when I re-start the server after doing that, I still get the message that "If you are seeing this page, it means that the OpenMRS Platform is running successfully, but no user interface module is installed"


    1. Same problem for me. Did you find where to place the omod file?

      1. It's not there AFAIK. In windows, you can press Ctrl+R. It opens up the run dialog.  tpye %APPDATA%. This will open your local files. Go to OpenMrs->module and place it there. I have been LUI for past 1 month (smile)

  3. I get an error running mvn clean install:

    I am using Maven 3.3.3, Java 1.8.0_25

  4. Dominic Surrao  You need to checkout 2.0.x branch on core and build it locally then rebuild legacyui, sorry a CI plan for the branch to have these snapshots deployed to nexus automatically on every commit, is still to be created.

    For others having this issue and the above statement is not clear on how to fix it. Run the following commands


    cd openmrs-core

    git fetch upstream 2.0.x:2.0.x       NOTE: Skip this step if you already have 2.0.x on your branch own your local repo, i did not have it since i forked the repo a long time a go, but you may have it

    git checkout 2.0.x   

    mvn clean install


    You can now build legacyui, using the instructions on this wiki.


    1. I was getting the same errors as Dominic and I followed these instructions. Now I get different errors, mostly about packages not existing: javax.servlet.jsp,  org.jfree.chart. 

      Any thoughts?


  5. I saw that yesteday and was hoping that it would have been fixed before today. If you are blocked you can checkout ea70f6afa92bca449add6ee653eeeada7ccee242 while on 2.0.x branch of core and build, this is a the commit from Wyclif Luyima.  Then build legacyui again. This time, core will build successfully but you should have 1 test failure on legacyui, which can be skipped by adding the maven argument -DskipTests=true , or just add @ignore attribute to the failing tests. Take a look at this thread on talk if this does not help.


    1. Thanks much - not blocked, just building everything for the first time as a newbie developer. I can wait until this is fixed.

  6. I looked at this some more and the recent commit didnt help me.  The errors seem to be because 1.9 had for example org.openmrs.web.servlet and 2.0.x does not (because you have removed the gui).  The pom.xml in openmrs-module-legacyui/omod has a dependency on org.openmrs.web - but wouldnt this be the new version ?  If so -> I don't see in the pom.xml where the old web modules are brought in?   (note I am a newbie here!)

    1. That should have worked, it did for me and others, maybe you are doing something wrong.You can ping me on irc(l4rry) or post your problem on If you just want to explore the features of openmrs, i will advice you checkout the 1.11.x branch, that is stable and you will not need to install the legacyui, since this branch still has a user interface. If you are going through the developers guide, that branch will be good for you because the developers guide says nothing about the legacyui module.

    2. This seems consistent with the runtime errors I posted here:

  7. A little secret I use now when I find issues with a commit / branch is to either move backward to a prior commit hash or forward to a more recent one....

  8. I am all set - there is a pull request from kirstopherschmidt that fixed my problem.  His branch builds with no errors.

          git clone --branch LUI-52

          mvn clean install -DskipTests=true



  9. The legacy-ui module will not work with the 'master' branch of openmrs-core right? I've been trying for a long time but in vain


  10. I'm not sure why it built for Larry and others with just the addition of the fix to add xerces.  This wasnt my problem - it was what I described above, multiple errors because when the GUI was split off, there are new dependencies that are needed to be added to omod/pom.xml. There is a pull request from kirstopherschmidt that fixes this.  You can build from his branch - the only difference is that pom.xml.

  11. I managed to get it running with the 2.0.x branch on core. There are issues with the latest builds of 2.0.X and the legacyui module (tongue)

  12. Thanks - I must have something missing in my setup. (sad)

  13. Hold on I've run into the error again. Idk it buld the first time and now there's an error on running mvn jetty:run

    Was it something like cannot find url mapping etc etc? Can you post a screenshot?

    1. No - I am using Tomcat, not Jetty,  It was a bunch of compiler errors with taglib and jfreechart not found.

      1. Any chance you can post a screenshot?

        Also, try doing

        `git reset --hard ea70f6afa92bca449add6ee653eeeada7ccee24`

        on openmrs-core. Then try using legacyui


  14. That did it !!    Thank you so much.  So I guess I was not actually building the branch that I thought I was.

    Sorry to waste yours and Larrys time.

  15. Lawl i'm a newbie as well. Just figured it out on my own. What your are essentially doing is reverting back to a stable version. Wyclif Luyima Help! I think the legacy UI and latest 2.0.x application needs some work done!

  16. Latest update: To work on the legacy-UI module, continue using the latest build of core 2.0.X and latest build of legacyUI. However, while building legacyui, instead of `mvn clean install`, type `mvn clean install -DskipTests=true`. This will build successfully and you can continue working normally until Wyclif Luyima fixes this issue.