Lesson 0: Getting started with WebGL

Lesson 1 >>

[This post has been updated several times since it was originally written, as things have moved on a bit since it was originally published in October 2009... to the best of my knowledge, information is correct as of 17 January 2012.]

The first step in trying out WebGL is to get a browser that supports it. How you do that depends on whether you want to look at cool WebGL demos or develop your own.

Keeping it simple

In general, I recommend that if you want to take a look at cool WebGL demos and aren’t really worried about developing your own, and don’t really care that some of the very latest stuff might not work, then:

  • If you’re on Windows, make sure you have the Microsoft DirectX runtime installed — this is a free download from Microsoft.
  • Once you’ve done that, make sure that you’ve got the very latest versions of the drivers for your graphics card.
  • Next, choose your browser:
    • Firefox: just make sure you have version 4 or higher.
    • Chrome: all you need to do is install it, or if you’re already using it, just check whether it’s updated itself to version 10 — this will almost certainly have happened automatically (it was released in March 2011), but you can check from the “About Google Chrome” option on the tools menu to confirm.
    • Safari: on Macs, OS X 10.7 has WebGL support, but it’s switched off by default. To switch it on, enable the developer menu and check the “Enable WebGL” option. (Thanks to Blah for the heads-up on this one.)

That’s it! You should be good to go. Next, click here to try out some WebGL pages.

Doing it the hard way

If you’re developing WebGL yourself, or if you need the latest features, then nothing beats having the very latest browser. And WebGL is supported in development versions of all of the main browsers apart from Internet Explorer, so all you need to do is get the appropriate version for your machine. How easy this is depends on what kind of computer you have:

  • Windows: If you haven’t already done so, make sure you have the DirectX runtime installed — this is a free download from Microsoft. Once you’ve done that, install either Firefox or Chromium, whichever you prefer — if it doesn’t work, check out the troubleshooting guide. (Stop press: a pre-beta version of Opera that supports WebGL on Windows is now available; it’s less stable than the other browsers, though, so don’t rely on it as your only WebGL implementation. It will also only work if your graphics card supports OpenGL 2.0, so it might be a pain to get working.)
  • Macintosh: if you’re running Snow Leopard (OS X 10.6), things should be fine; I recommend that you use the development version of WebKit, which will run as an alternative version of Safari. If you’re running Leopard (OS X 10.5), then you won’t be able to use that version of WebKit, but you can run either Firefox or Chromium. Snow Leopard users can use Firefox or Chromium too, of course. If you’ve got an older version of OS X, unfortunately I don’t know of any WebGL browser you can use right now :-(
  • Linux: quite a large number of Linux graphics drivers are, sadly, not good enough to work with WebGL. The same used to be the case under Windows, but the browser makers worked around it using DirectX; unfortunately there’s no such escape route for Linux. Here’s what I’ve managed to gather:
    • If you’ve got Nvidia graphics, and recent drivers, then things should work just fine with either Firefox or Chromium.
    • If you have ATI graphics, you’re probably best off with Firefox.
    • If you have Intel graphics, you’re likely to have to use slow software rendering, which sucks but at least lets you see some WebGL stuff; try Firefox or Chromium, but they probably won’t work with the default (hardware rendering) setup. To use software rendering on Linux, you need to make sure that Mesa is installed (you should just be able to get the latest version using your distro’s package manager) and then you can use the latest Firefox with a few extra settings.

    There’s more detail about this in the troubleshooting section below.


The “unstable” development release of Firefox is called Minefield. It’s updated every night, and it’s actually pretty solid right now: I’ve not seen it crash recently (and I use it for everything). It can be installed alongside a regular version of Firefox, too, so you don’t need to worry about uninstalling it if you give up on it, or just want to switch back to the regular version for a while.

To get Minefield:

  • Go to the nightly builds page and get the appropriate version for your machine. Look out! There might be various versions there, with names like firefox-10.0a1something or firefox-10.0a2something. You want the most recent, which will be with the highest number after the ‘a’ (alpha) or ‘b’ (beta).
  • Install it (you’ll need to quit any running Firefox instances while this happens).
  • Start Minefield.

A useful tip — if you want to run Minefield side-by-side with the regular Firefox, you can do this by adding the following command-line parameters: -P Minefield -no-remote. The first parameter makes it run with a separate profile (so that you keep separate histories and sets of active tabs in each browser) and the second means that when you start Minefield while Firefox is already running, it won’t just open a new window in the currently-running Firefox. You might also want to add -P default -no-remote to the parameters for your normal Firefox to do the same there too. Windows users: you can set the command-line parameters for each application by right-clicking on the icon you use to launch it, selecting “Properties”, and adding the parameters to the end of the “Target” field. Mac and Linux users — I don’t know how you do it, but you probably know anyway ;-)

Next, click here to try out some WebGL pages.

Running Minefield with Software Rendering on Linux

If your graphics hardware or — more likely — driver doesn’t support OpenGL 2.0, then right now the only way to get WebGL working on Linux is to use a library called Mesa. Mesa basically emulates a graphics card in software, so it’s a bit slow — but it’s better than nothing. It integrates with Minefield, the “unstable” development release of Firefox, and it’s normally part of your Linux distro. Here’s how to get it working.

  • Download the latest version of Minefield.
  • Install it (you’ll need to quit any running Firefox instances while this happens).
  • Using your Linux distro’s package manager, make sure that you have Mesa installed and updated to the latest version.
  • Start Minefield.
  • Go to the page “about:config”
  • Filter for “webgl”
  • Switch the value “webgl.enabled_for_all_sites” to “true”.
  • Switch the value “webgl.software_rendering” to “true”.
  • Set the “webgl.osmesalib” setting to the location of your OSMesa shared library (normally something like /usr/lib/libOSMesa.so).

Once you’ve done all that, you should be set. Click here to try out some WebGL pages.


Remember, Safari only supports WebGL on Macs running Snow Leopard (OS X 10.6); if you’re on Leopard (10.5), Windows or Linux then you’ll have to use Firefox or Chromium. (If you’re on an older version of OS/X, I don’t know of any browser you can use :-( )

If you are on Snow Leopard, to get it running, you need to:

  • Make sure you have at least version 4 of Safari.
  • Download and install the WebKit nightly build.
  • Start up a Terminal, and in it run this command:
    defaults write com.apple.Safari WebKitWebGLEnabled -bool YES
  • Run the freshly-installed WebKit application.

Next, click here to try out some WebGL pages.


The way the Chrome developers currently recommend you get WebGL in Chrome, if you’re doing WebGL development, is to use a nightly build of Chromium, the open source browser on which Chrome is based. The procedure is a little different for each supported operating system; here are instructions for Windows, Macintosh, and Linux. (A warning — I’ve only tried the Windows version myself, but I’m told the other versions work fine too. Leave a comment below if I’m wrong on that :-)

For Windows

  • Go to the continuous integration page, scroll down to the most recent build (at the bottom), click on the link, and get chrome-win32.zip
  • Unzip the file somewhere convenient.
  • Inside the unpacked directory, double-click the chrome.exe file.

For the Macintosh

  • Go to the continuous integration page, scroll down to the most recent build (at the bottom), click on the link, and get chrome-mac.zip
  • Unzip the file somewhere convenient.
  • Open a Terminal window, and go to the chrome-mac directory that you unzipped.
  • Make sure you’re not running Chrome already
  • Run the following command:
  • Once you’ve checked that it works, you might want to automate things a bit so that you don’t have to type the command line every time; in the comments, Julien Limoges has provided a useful shell script to handle that.

For Linux

  • Go to the 32-bit or the the 64-bit continuous integration page as appropriatescroll down to the most recent build (at the bottom), click on the link, and get chrome-linux.zip.
  • Unzip the file somewhere convenient, and go to the chrome-linux directory that you unzipped in a terminal window.
  • Make sure you’re not running Chrome already
  • Run the following command:

Next, click here to try out some WebGL pages.

Some first examples

Once your browser is installed, you should be able to see WebGL content.  Here’s a first sanity check; WebGL Report, which gives details of the WebGL features enabled on your browser. If it tells you that your browser doesn’t support WebGL, check out the troubleshooting guide below.

If it did work, everything should be set up! Unfortunately some recent changes to WebGL broke many of the demos out there, but here are some that have been updated:

That’s it for my first post on getting started with WebGL. If you want to go further and learn about how to create your own WebGL pages, you can check out my first WebGL lesson.

Lesson 1 >>



I don’t have any useful hints and tips for getting WebGL running on Macs, because no-one’s ever asked me for help and I don’t think I’ve ever seen questions in the forums. I can only assume that this means that Everything Just Works on OS X…


The most common problem for Windows users is that you don’t have the DirectX runtime installed — this is a free download from Microsoft, so give it a go. It might also be worth seeing if there are more up-to-date drivers for your graphics card — check out Windows Update, or perhaps the website of your graphics card manufacturer. If that doesn’t work, it might be that your graphics driver is on a “blacklist”. This is rarer under Windows than under Linux, but has been known to happen. See the Linux instructions below for some hints.


The most common reason for WebGL not working under Linux is problems with graphics drivers. All current Linux browser implementations of WebGL are based on OpenGL, and OpenGL support is something that is provided by your graphics driver. WebGL needs at least OpenGL 2.0 in order to run; in particular, owners of Intel graphics cards have problems because Intel haven’t released drivers for most of their graphics hardware with support for that. If you have Intel graphics, try using Mesa software rendering. If it’s still not working, leave a comment below and I’ll try to help.

If you have ATI or Nvidia graphics, the first thing to do is check the version of OpenGL you have on your machine. To do this, run glxinfo and look for the line headed “OpenGL version string”. If the version number you see is less than 2.0, you’ll need to update your drivers. Check out your computer/graphics card manufacturer’s website, and have a look at distro’s package manager.

If you still can’t get things running, it may be that the browser makers have “blacklisted” your driver; this is because some of them are unstable enough to cause machines to crash, which is understandably not behaviour people want associated with the browser…

In the comments to this post, Nardon gives this update as of 6 October 2011 “Google blacklisted all Linux Drivers, except for the official nVidia Drivers … Firefox 6 and above whitelisted most newer ATI drivers for Linux so you should be able to use WebGL with this browser.”

If you want to risk crashes, and use a blacklisted driver, you can start Chrome with the command-line flag –ignore-gpu-blacklist and see what happens (thanks to Jonas Antunes da Silva for that tip). If it doesn’t fix things, it may just be that a decent Linux OpenGL driver isn’t available for your graphics hardware. Your best bet for now is probably to use software rendering. Once again here are the instructions.


Thanks to Vladimir Vukićević, Mohamed Mansour, Ehsun Amanolahi, and Chris Marrin for the information that made up this page, and all of its many previous incarnations!

You can leave a response, or trackback from your own site.

225 Responses to “Lesson 0: Getting started with WebGL”

  1. Milos says:

    I don’t understand what is happened with minefield?
    I installed it one month ago and configure it following your instruction in this lesson. I tried to start working on project but if i try to open some demo my browser is crashed.
    After i try all the same on notebook and repeat all of this instructions i get message that webgl could not be initialise, sorry :-(

    Can someone help me? I am totally new in this.

  2. smindel says:


    regarding my earlier post: minefield 3.7a5 doesn’t work for me. if you don’t want to wait for the fix you can use an older version:



  3. giles says:

    @smindel — that’s a great solution, thanks for posting it!

    @Milos — the simple description of the Firefox problem is that they made a change that stopped its software rendering from working with the version of OSMesa32.dll that a lot of people (perhaps including you) had downloaded. They intend to fix the problem by producing a new version of OSMesa32.dll, but they haven’t done so yet. smindel’s suggestion of using the older version is the best way to go for now.

  4. Milos says:

    One more question,
    Does openGL 2.0 required?
    On my laptop i have integrated intel 965 graphic media accelerator which support opengl 1.5. I try to update graphic drivers and openGL too but my
    drivers is up to date.
    How i can upgrade openGL version?

  5. giles says:

    If Intel don’t support 2.0 in its drivers, then there’s not really much you can do right now. The OpenGL support is normally provided by the driver.

    If you want to try WebGL, you have to either (a) wait for ANGLE or (b) use Firefox with Mesa software rendering, by using smindel’s link to the old version.

  6. Milos says:

    Cool, now it works

  7. fenton says:

    I’m on Mac OS/X 10.5 (Leopard) and neither Firefox(aka: Minefield) or Chromium works for me. Chromium loads up but doesn’t load WebGL pages. Minefield doesn’t even open up.

  8. fenton says:

    tried the same thing with nightly build of firefox and chromium on ubuntu 10.04…no luck…hmmmm..

  9. giles says:

    @fenton — that’s odd. Do you see anything in the Chromium error console?

  10. Bart says:


    I’m using chrome 5 (public release, not the nightly build) on windows vista, and most of the time, the textures don’t show up on the models at all.
    More specifically, lesson 6 works as intended, but lesson 7 does not. I get a white (non-textured) box.
    I encountered similar problems at other sites hosting examples…

    Nothing in the error console.

  11. giles says:

    Hi Bart,

    That’s odd, but to be honest the public release’s WebGL implementation is very incomplete; if you want to see WebGL content I really recommend using Chromium nightly builds.


  12. Bart says:

    Just tried the latest nightly build, same problem. However, this time I get 2 warnings:

    Calling obsolete texImage2D(GLenum target, GLint level, HTMLImageElement image, GLboolean flipY)
    Calling obsolete texImage2D(GLenum target, GLint level, HTMLImageElement image, GLboolean flipY, GLboolean premultiplyAlpha)

    They seem to be related to my problem I think?

  13. giles says:

    That’s interesting. I see the same warnings (which I clearly need to fix) but I don’t get the problem you’re seeing — all of the demos show the textures correctly. What kind of graphics card do you have? Do you have the latest drivers installed for it?

  14. Bart says:

    Okay, apparently it was a driver problem. Sorry for wasting your time :-/

  15. giles says:

    Not a problem, glad you’ve got it working!

  16. gg says:

    i would like to know hoow to make opengl2.0 work for fennec i.e mobile firefox

  17. giles says:

    Hi gg — as far as I can tell, the Mozilla team do have code that enables WebGL (which is based on OpenGL ES 2.0) in Fennec for the Nokia N900 phone. However, I don’t think that’s in any released version yet.

  18. Georgi says:

    Hi, what’s wrong with minefield after 3.7a5pre. After update webgl stop working. Are we have new OSMESA32.dll or something else?

  19. giles says:

    Not sure yet — I *think* the Mozilla guys are going to make a new OSMESA32.DLL, but I can’t say for sure.

  20. Georgi says:

    So, there is no way to use webgl after minefield 3.7a5pre. Is that true?

  21. giles says:

    If you need to use software rendering, that’s right. Obviously there will be a fix of some kind, but it’s not certain yet exactly what they will do.

  22. Georgi says:

    Thanks, giles. Will webgl work fine with minefield after 3.7a5pre if my video card support OpenGL 2.0, without .dll?

  23. giles says:

    That’s right. Software rendering is only needed if your graphics card doesn’t support OpenGL 2.0.

  24. Milos says:

    Hey, I have one debugging problem!

    why minefield doesn’ t have support for javascript console (for example firebug). Is there any option to enable console in minefield and how?
    In case minefield doesn’t support any add-ons how i can track my javasctipt data and webGL also.

  25. [...] wie man unter Windows, Linux oder Mac WebGL fähige Browser einrichten kann, findet man hier. Diese Blog-Reihe beschäftigt sich vor allem mit Code und praktischen Anwendungen von WebGL, [...]

  26. I though this little script could help a few others to make your Chromium app start with WebGL enabled on OS X.

    It simply is a bash script that generates another bash script that is called when you click on the Chromium.app and passes the –enable-webgl argument to the executable. Here it is :

    # Allows your Chromium executable to launch with WebGL enabled
    # by Julien Limoges, 2010/07/05
    mv $MacOS/Chromium $MacOS/Chromium.executable
    touch $MacOS/Chromium
    cat > $MacOS/Chromium << EOL
    exec \`dirname \$0\`/Chromium.executable --enable-webgl "\$@"
    chmod 755 $MacOS/Chromium

    If you want to remove it you can simply do :

    mv /Applications/Chromium.app/Contents/MacOS/Chromium.executable /Applications/Chromium.app/Contents/MacOS/Chromium

    Happy work with WebGL!

  27. Julien says:

    If possible, can my email be removed from the previous comment, I copy/pasted away and forgot to remove it.

  28. giles says:

    Hi Julien,

    Thanks for the script! I’ve removed your email, and will put a link to the comment into the body of the article.



  29. Tom says:

    Bart, I am having the same problem:
    Calling obsolete texImage2D(GLenum target, GLint level, HTMLImageElement image, GLboolean flipY)
    Calling obsolete texImage2D(GLenum target, GLint level, HTMLImageElement image, GLboolean flipY, GLboolean premultiplyAlpha)
    Which prevents procedural textures working.

    I have the latest chromium, using NVidia GeForce 9300, openGL 3.3, latest drivers from yesterday. The only clue is that I am using an intel laptop, do you think I just have unfortunately the wrong graphics card?

    What did you do that fixed the problem for you?

  30. giles says:

    Hi Tom — the Intel problem is with their graphics cards, not their processors, so if you’ve got an NVidia graphics card you should be fine. I think the messages you’re seeing are warnings rather than errors; is there a particular page that’s not working that you could leave a URL for?

  31. [...] my favorite WebGL learning resources during the past half of year, except the famous LearningWebGL.com, there’re many WebGL frameworks and resourses we can [...]

  32. [...] This demo requires a WebGL capable browser. Installation instructions can be found at Learning WebGL or the WebGL [...]

  33. Benoit Jacob says:

    Just commenting on this:

    “that said, as of 22 June 2010 I’ve been hearing about problems with Firefox WebGL support on 64-bit Linux”

    The problems we had with Linux should be fixed by now — though we’re always interested in bug reports ;-)

  34. giles says:

    @Benoit — thanks! I’ve updated appropriately.

  35. Steve Baker says:

    The demo seems to be broken in recent Minefield build and that’s because you’re still using the old form of gl.createTexture() which was obsoleted a week or so ago:

    Error: uncaught exception: [Exception... "Not enough arguments" nsresult: "0x80570001 (NS_ERROR_XPC_NOT_ENOUGH_ARGS)" location: "JS frame :: http://www.nihilogic.dk/labs/webgl/gl.js :: createTexture :: line 288" data: no]

  36. giles says:

    Hi Steve,

    Thanks for the comment, but I think you meant to post it on one of Jacob Seidelin’s demo pages? I don’t think any of the examples on this site are broken.



  37. xnebiax says:

    Hey, smindel ’s link to the old Minefield is not working enymore… ca somebody retrieve that version and send it to me somehow? or put a new link?

  38. giles says:

    @xnebiax — if you need that build so that you can use sofware rendering, you might be able to use the latest build instead — there’s a new OSMesa.dll binary available that works with the current nightly builds. I’ve updated the instructions in the blog post with the new details.

  39. mhack says:

    To get webgl working with Minefield 4.0b5pre on my macbook OSX 10.5.8 I had to go into about:config and set webgl.enabled_for_all_sites to true. After that it worked great.

  40. mhack says:

    Oh, I just spotted the about:config in the Firefox instructions above, duh.

  41. [...] The Audio Data API is now available. See David’s blog post here (see screencast below) and try the demo here (better if WebGL activated) [...]

  42. Miro says:

    Hi, in minefield (windows + mac OS) all examples causing a crash…any idea why?
    + thanks for the great tutorials

  43. sreejith says:

    I can’t make webgl work.

    I’m using ATI Radeon 5650 with opengl version 3.0 and FireFox 4.0 Beta 6 edition.

    Edited about:config with following values

    But still it’s not working for me.

    Please Help!!!!!

  44. sreejith says:

    Also tried with OSMESA32.dll but still it’s not working!

  45. giles says:

    @Miro — it might have just been a bad build, have you tried any of the more recent ones?

    @sreejith — that certainly sounds like it should work — it might be worth switching off the mochitest one and trying with the most recent build, though.

  46. [...] is a comprehensive guide at Learning WebGL, and I will just briefly touch on it [...]

  47. [...] WebGL is basically a JavaScript API built on top of OpenGL, the standard graphics library in use today for 2-d and 3-d renderings and desktop games which directly utilizes your systems graphics card. Since it is still under development, it’s not included in any browser downloads by default. You’ll need to manually activate WebGL [...]

  48. Roberto says:

    Thanks for these examples of your site

  49. Vincent Scheib says:

    The easiest method to use the latest version of Chrome is the Canary build:
    It’s only supported on Windows just now though. It will auto-update, and webgl is enabled by default.

Leave a Reply

Subscribe to RSS Feed Follow Learning WebGL on Twitter