Getting Qt and Ruby (=QtRuby) running on Windows XP

Important note

An update on this post is available here. The improvements are

  • only 6 steps instead of 10
  • QtRuby 2.1.0 instead of whatever old version is installed by the guide below
  • Qt 4.6.1 instead of Qt 4.3.4
  • Ruby 1.8.7 instead of Ruby 1.8.6

This is a tutorial about writing Ruby applications that use the Qt framework on Windows XP. For doing so, the Qt-Ruby bindings named QtRuby are used.


Ruby programs that have a nice GUI? Is that possible? With all that Ruby On Rails stuff going on, good old desktop applications have been left behind. And so has the topic of creating a desktop application that is pleasant to use and to code.

When combining Ruby and Qt, developers finally have a chance to create Ruby GUI applications that are neither pain in the ass for developers nor pain in the eye for the user.


At the time of writing this I have very little experience with QtRuby. However I just wanted to get started with it and did not find a decent guide for doing so on windows, so I just put together what I learned in the first few days.
For the sake of simplicity and brevity, this guide does not use the latest versions of Ruby, Qt and QtRuby. Instead, it is using prebuilt binaries and installers, that have been created by some nice guys (for getting the latest version running, see comments).
You have been warned. Comments are welcome.

Setting everything up

Getting your first QtRuby program to run under windows is surprisingly simple.

Installing Ruby

  1. Download the Ruby One-Click Installer from the official Ruby site: Make sure to use that exact version. Otherwise you might run into dll-version problems (see Yann’s comment for details).
  2. During installation, check the SciTE and Enable RubyGems options. SciTE is an editor and Gems is the Ruby package manager (we won’t need those here, but they are both very handy tools).
  3. Install to c:\ruby. You may of course choose a different path, but for the rest of this guide I will assume this location.
  4. When installation is finished, open a shell and type ruby --version. It should say ruby 1.8.6.

Installing Qt

  1. Download  Qt 4.3.4 Open Source Edition from and install it.
  2. During installation,  check the Install mingw option (if you do not yet have mingw installed). mingw is a gcc (C++ compiler) for Windows. Qt 4.3.4 Open Source comes with precompiled binaries that need the runtime dll (mingwm10.dll) of mingw.
  3. To check, whether the installation worked, go to Start->Programs->Qt->Examples and Demos. You should see a window with fancy animation that offers various examples of Qt in action.

Installing QtRuby

  1. Get the installer from and install it.
  2. Open irb (that’s a Ruby shell) by typing irb at your Windows shell.
  3. Type require 'Qt4' and execute it by pressing Enter. It should yield true

That’s it! Now you are ready to begin development of QtRuby programs.
You may leave now if you want and hack away on your own. However, if you want some advice on how to start and where to get information, I kindly invite you to stay a bit longer.

Hello Qt, Hello Ruby!

Let’s see if we can greet our new friends. Type the following program into the irb. Alternatively you may copy-paste the code into a fresh file. Name it main.rb and run it with ruby main.rb.

require 'Qt'
app ="Hello Ruby, hello Qt!")

Hello Ruby, hello Qt

You should see something that looks strikingly similar to the screenshot.

Getting Help on Qt
Qt is the best-documented library I have ever seen. You can find everything at
(The QtRuby version you downloaded has been built against Qt 4.3.1)

The docs are available as an offline version: If you install and compile an open source version of Qt (see this post ), you will get a program called Qt Assistant (assisstant.exe) that offers the full documentation and some neat searching features.
When installing Qt, you will also get a nice program called qtdemo.exe. It contains lots of example programs (in fact the Regular Expressions ‘example’ is one of my favorite tools at work).

However, there is one drawback on both, the documentation and the example programs. It is all written for C++ coders. Damn!
Fortunately the difference between C++-Qt and Ruby-Qt is not that big. But it gets even better…

Tons of Examples (in Ruby!)
…because a very kind guy named Richard Dale converted the Qt examples from C++ to Ruby. They come with the QtRuby source package, that can be found on the Rubyforge homepage of Korundum/QtRuby ( Let me show you how to get them running (and introduce you to the resource compiler on the way).

  1. Download e.g. qt4-qtruby-1.4.9.tgz and unpack it
  2. Browse to the directory qt4-qtruby-1.4.9\ruby\qtruby\examples\graphicsview\collidingmice and open a shell
  3. Type ruby main.rb
  4. And tadaah – you will get an error message saying no such file to load -- qrc_mice.rb (LoadError)

The reason for this error is that the resources (images in this case) have to be available for the program to work. To create the required resource file, we have to execute the Ruby-pendant of the Qt resource compiler (rbrcc, probably located in c:\ruby\bin)
rbrcc mice.qrc -o qrc_mice.rb
Try ruby main.rb again. This time you should see a window with some mice running around in it.

Colliding Mice Example in Ruby

More, More, More
When finished with this short introduction, I strongly recommend to check out
immediately. It explains how the concepts of Qt/C++ translate to QtRuby, gives a few nice tricks, that are not possible in C++ and demonstrates some convenient features of QtRuby. There’s also a bunch of links at the bottom of that page, that points out more resources to learn about QtRuby.
Great stuff, one small warning: It appears that the example code is written for Qt 3.x. So keep that in mind when copy-pasting it.

Well, that’s it for now. Happy coding!

28 thoughts on “Getting Qt and Ruby (=QtRuby) running on Windows XP

  1. admin Post author

    Hi lucksus!
    You are correct, getting the latest version running is quite simple. However, since it requires installing Visual Studio Express, and since I wanted to show the most simple way of getting started, I did not use the latest version for this guide.
    However, thanks for pointing that out. I will add a hint to your comment.

  2. Saurabh Bhatia

    I am working on an app with QtRuby, Postgres. I have finished making everything and now want to package my app as MSI installer or something of that kind.

    Do you have any resources for that ?



  3. Narasimha Raju


    I developed an application using QtRuby and Postgresql in Linux. It is runnuing sucessfully. Now i want to run the same application on Windows. I installed Ruby, Qt and Postgrsql on windows. While running i am getting the following errors:

    QSqlDatabase: QPSQL driver not loaded
    QSqlDatabase: available drivers: QSQLITE QODBC3 QODBC

    Can you help how to resolve my problem. Waiting for your reply.


    Narasimha Raju. Naidu

  4. admin Post author

    Hi Narasimha Raju,
    I am afraid I do not have any experience in using Qt’s SQL Library and I never worked with Postgres.
    I suggest you try asking that question on or in forums/mailing lists of Qt or Postgres.

  5. Narasimha Raju


    I tried all the ways. I created qsqlpsql.dll also but still i am getting the same error. I think you can resolve my problem. Even i posted in but i sis not e any responce.

    Try from your side also.

    Waiting for your reply.


    Narasimha Raju

  6. admin Post author

    Hi Narasimha Raju!
    Your problem seems to be related to the combination of Qt’s SQL Library and Postgres. To help you resolve it, I would have to
    a) Install Postgres and get to know it
    b) Create a sample application or build your code.
    I would happily help you to resolve your problem, if it had something to do with one of my posts.
    However, since it the problem is unrelated to any area I am interested or competent in, I can only point you to resources, which might provide and answer. If they don’t, then you will have to dig into the problem yourself. If I am not mistaken, all the source code (Qt and Postgres) is available. This might be a lot of work, but you will surely learn much from it.

  7. Narasimha Raju


    Thanks for your reply. I will do according to your advice. I have one doubt regarding Packaging, i.e., i have developed one small application and made it package using NISI package software. My doubt is inorder to run any windows system it requires Ruby, Qt and QtRuby interpreter. In order to run an application all are must. Ruby S/W size is small and QtRuby intrepreter also, but installing Qt is a very big software. is there any alternative to run without installing Qt.

    waiting for your reply,


    Narasimha Raju

  8. admin Post author

    Hi Narasimha Raju!
    For running a QtRuby program, the Qt Dlls have to be present on the machine. And that will take up a few megabytes. There is no way around that. But considering today’s hard disks, that is probably not a problem, however bandwidth might be a small problem. The QtRuby program as a whole is probably too large to be sent via mail.
    For packaging the program (that is the Ruby application, the Ruby interpreter and the Qt Dlls) I strongly recommend using tar2rubyscript and
    rubyscript2exe as described here:
    Then your users will just install one .exe file and are done. They do not even notice that it’s a Ruby program.

  9. Narasimha Raju


    thanks for your reply. I will go through your post and i will do it once again. Once again thanks for your reply.


    Narasimha Raju

  10. Pingback: Qt and Ruby on Windows and Mac « The Curious Penguin

  11. Matthew Borgeson

    I wanted to first thank yo for the excellent tutorial on getting Qt4/Ruby up and running under windows.

    Secondly, while I have it all up and running, after I tried to run my first form, I get the following error:

    c:/ruby/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:31:in `gem_original_require’: no such file to load — korundum4 (LoadError)
    from c:/ruby/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:31:in `require’
    from assh_at_windows_main.rb:10

    Does this mean that I do not have korundum4 installed and that I need to download it from somewhere?? If so, where should I get it from?

    I have google this ad nauseum and am hoping you can help. If not, thanks for perusing this emai anyway, and thanks again-

    Matthew Borgeson

  12. admin Post author

    Hi Matthew!
    Thanks for your kind words regarding the tutorial.

    The problems you have looks strange to me, because QtRuby should run without korundum. If I am not mistaken, korundum is a ruby binding for the KDE API. Unless you install KDE on Windows, it can not be used and probably not be installed on Windows.
    On my ruby installation, the only file that requires ‘korundum4’ is a file named ‘rbqtapi’. However, it only requires ‘korundum4’ if it is called from a file named ‘rbkde4api’ – a file that does not exist on my system.
    Hence I wonder, where that error message of yours comes from. Can you try to pinpoint that?
    Furthermore make sure that you installed the correct qtruby version, which is qtruby4, version 1.4.9 for win32.
    You can find the details about your installed qtruby gem by typing
    gem specification qtruby4.
    Another question: When you open the irb and type
    require ‘Qt’
    does it work or do you get an error message?

  13. bowen

    Hi Tom

    I’d just like to point out that where you say “You don’t even need to install Qt”, is completely false 🙂
    If you don’t install Qt, then there are no Qt dlls present on the system for qtruby to bind to, and the installer you linked will refuse to even install the bindings.
    It’d be nice if there was a place to find JUST the runtime DLLs needed for Qt without all the crud in the trolltech installer (which for the latest version is now 260MB!)

    Did you ever manage to get a Ruby/Qt4 program working using OCRA / RubyScript2Exe by the way? I can’t work out how to get it to pull in the relevant Qt DLLs and therefore work on a virgin windows box by just running the EXE.

  14. admin Post author

    Hi Jim!
    Thanks for your comment.
    You are absolutely right about me being completely wrong regarding the installation procedure. I corrected the post.

    As for the large installer of Qt, here are my remarks:
    – the post now links to a version of Qt that only has 70 MB.
    – there also is a gem named “qtruby4” that exists in a win32 version and comes with all required binaries. In fact I considered that gem for this blog post

    And finally on the issue of deployment:
    I do not currently have good a way of deploying Qt Ruby applications. RubyScript2Exe does not seem to work with newer version of gems and I could not get OCRA to work for my application either. However, the developer of OCRA Lars Christensen would probably be happy to fix it, if someone would provide him with a small test application. I did not yet find the time to do that.
    In any case, here is a list of dlls that I currently use for my deployment-workaround:
    Hth, Thanks again for your correction

  15. Yann


    I am trying to make it work on Windows XP.
    Installed all you said, although the ruby one click installer provides this version :
    ruby 1.8.6 (2008-08-11 patchlevel 287) [i386-mswin32]

    I followed your tutorial, only one I was able to find on the web.
    Unfortunately, it keeps telling me an entry point is not available in the QtCore4 dynamic library (_Z10forcepointR11QTextStream).

    Tried with other Ruby version (1.8.6 26), same problem.
    Any clues on the exact Ruby version you’re using ?

  16. admin Post author

    Hi Yann!
    Thank you very much for your hint. I modified the tutorial accordingly.
    It seems to me that it gets harder an harder to get QtRuby running on windows, simply due to the fact that no new QtRuby version for windows are available at the moment. Nobody seems to be able to get QtRuby to compile on windows anymore. So if anybody reading this finds some time … 😉

  17. Karolus


    I’m also trying to get QtRuby working on Windows NT, but so far I’m getting the same problem as Yann.

    I installed:
    – ruby (the exact version mention; I used Yann’s url),
    – Qt (version Qt-4.3.4 Open Source Edition using the link on the web page
    – qtruby4installer.exe from the same webpage

    and also got the error about (_Z10forcepointR11QTextStream) being missing from QtCore4.dll.

    So my questions are:
    (1) Has anyone checked if the links all point to the correct versions recently?

    (2) I do have various other versions of QtCore4.dll that come with compiled application like Merkaartor, but the QtRuby installer lets me set the path, and I made sure that it points to the right Qt version; I also checked the PATH variable.

    (3) How do I make absolutely sure which QtCore DLL is being used when I start irb?

    Best regards,


  18. admin Post author

    Hi Charles!
    (1) A day or two after Yann’s comment , I tested the whole tutorial on a fresh Windows XP SP 2, but not on Win NT.
    (2) The search-sequence for dlls is explained here:
    (3) According to (2) I would recommend to put the dll in the bin-directory of ruby. You can use the tool process monitor to see the dlls that are used by a process.

  19. Karolus


    I simply copied all DLLs from the Qt 4.3.4 directory to the directory where the Ruby bin files reside. That worked.

    Err …a mistake on my part: I was testing with Microsoft Windows XP, not NT.



  20. Matthew Borgeson

    Long time since a response, just wanted to let you know I did have the wrong version of installed! Funny thing was, I had just gotten it running and then found myself using my Linux dev box more often at home for a Rails app for work and have yet to touch it since…*sigh* the trials and tribulations of gainful employment!

    Thanks again for everything-

  21. Dr1Ku


    Thanks for the excellent article, I’ve followed it and got it running.

    Here are my environment’s specs:

    Windows 7 x64
    Ruby 1.8.7-p248-i386-mswin32

    Copying all 14 dlls from Qt’s bin folder did the final trick as well.

  22. Pingback: ThisIsNotATest » Blog Archive » Getting Qt and Ruby (=QtRuby) running on Windows 7 (and Windows XP)

Leave a Reply to Matthew Borgeson Cancel reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.