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. Here is an updated link to chromium linux64 download:


    Cheers for the amazing site.

  2. Thai Tran says:

    I’ve tried all exercises. They all worked except Lesson 8 with “Use blending”. Can you help?


  3. giles says:

    @Roberto — no problem!

    @Vincent — the problem I’ve seen in the past with the auto-updating versions is that they’ve pulled WebGL support without warning a few times. In general, it has been safer to rely on Chromium nightly builds. That might be no longer the case, though.

    @Ehsun — thanks! I will update the post.

    @Thai Tran — looks like something’s stopping that one working in Chromium, not sure if it’s my problem or theirs. I’ll take a look and update it if necessary — keep an eye on the comments for that post for details.

  4. [...] Getting a WebGL browser Note: If you have Chrome version 7+, you just need to enable it with chrome.exe –enable-webgl [...]

  5. Henry P. Day, Jr. says:

    I tried to use your link from Vladimir to get the Mesa .dll file,


    and got an error 404 message. Can you update your link?

  6. giles says:

    Thanks for the heads-up, Henry — looks like my instructions are out of date. I’ll fix them ASAP. In the meantime: as of Firefox 4 beta 8, you probably don’t need Mesa. Instead, try making sure you have the DirectX runtime installed as per this post on Vlad’s blog: http://blog.vlad1.com/2010/12/21/webgl-in-firefox-4-beta-8/

  7. wap-tek says:

    webgl = forced to use beta browser + 90 mb video driver ,
    = maybe see something

    vrml/x3d = find a decent plugin or viewer ,
    = all were less than 5 mb and worked over 10 years ago!

    why cant mozilla just use a generic vrml / x3d plugin and make it
    FAULT TOLLERANT = ignore the deliberate standards breaking
    that the major players did 10 years ago

  8. [...] just noticed in the release notes for Chrome the mention of Web GL .  So, I looked up some instructions to enable [...]

  9. F1LT3R says:

    Particle effects demo appears to be broken in both Firefox4 Beta8 and Chromium 10.


  10. Haisen says:

    Thank you.My firefox mozilla can run webgl now.

  11. giles says:

    @wap-tek — right now, sure. But things go in to beta browsers in order to go into production browsers later when all of the problems are fixed — that’s what the beta is for! So going forward, all browsers with the (hopefully temporary) exception of Internet Explorer will have WebGL support by default. It’s also worth noting that with VRML and X3D you can only do a subset of the things WebGL can manage. X3DOM is an X3D implementation on top of WebGL.

    @F1LT3R — thanks for the heads-up, I’ll remove it from my list and alert the Google guys so that they can fix it.

    @Haisen — glad to help!

  12. To start I am running a Window 7 64bit machine with an Nvidia graphics card.
    When I tried your second lesson “the results of my second WebGL lesson” it did not work. I followed you instruction and found the continuous integration page and saw the chrome-win32.zip file. Is there a 64bit version?

  13. giles says:

    Hi Michael — I use a Win7 64-bit machine (albeit with ATI graphics) and the Win32 Chromium works for me. I don’t think there is a 64-bit nightly build for Windows, anyway — not sure why. Perhaps you could try Mozilla Minefield and see if you have any more luck? Alternatively, was there anything displayed in the JavaScript console in Chromium?

  14. [...] want to install the developer channel of Chrome or else Firefox 4 to do the newer stuff like webgl: http://learningwebgl.com/blog/?p=11 )Insert a dynamic date here  Yin Huang The apparent difficulty of JavaScript depends [...]

  15. used chrome ,my system is windows xp ,i doesn’t open the webgl,please help me ,thank you!

  16. jatatar says:

    in ubuntu edited applications menu item for chrome to “google-chrome –enable-webgl” and it works fine. using latest stable build and repos from ubuntu tweak.

  17. aestheticsData says:

    works perfectly on OSX 10.6.4 with webkit !!!

  18. giles says:

    @china wenjie xiao — try making sure you have the DirectX runtime installed as per this post on Vlad’s blog: http://blog.vlad1.com/2010/12/21/webgl-in-firefox-4-beta-8/

  19. [...] für 3D-Grafik. Was damit möglich ist, zeigt eine Demo-Seite. Die Beispiele darauf funktionieren auch in anderen Browsern, etwa der aktuellen Beta des Firefox und der Entwicklerversion von [...]

  20. [...] updated its Chrome web browser to version 9.  Basically the biggest changes for users will be WebGL support and the Chrome Web Store.  If you’ve never seen WebGL in action check it out.   The [...]

  21. [...] WebGL is a Javascript API that makes it possible to create 3D graphics that update in real time inside the computers browser (FYI: I use Google Chrome a lot, so the following experiments are within Chrome). There is no need to download any special software or plug-in to see these 3D images. For some browsers, such as Chrome or Firefox, this technology seems to work flawlessly already. For Macs, Safari only supports WebGL on Macs running Snow Leopard (OS X 10.6)…other versions won’t work. To see if your preferred browser has the capabilities to run WebGL, click here. [...]

  22. [...] Firefox:WebGL工作在 Windows、Mac OS X和Linux中每日构建(Nightly Build,也 叫Daily Build), 是将一个软件项目的所有最新代码取出,从头开始编译,链接, 运行测试软件包对代码进行单元测试 并对主要功能进行测试,发现错误并报告错误的完整过程。——译者注)的Firefox开发版上。点击此处了解如何安装支持WebGL的Firefox。如果你使用PC机,建议用Firefox。 [...]

  23. [...] Lesson 0: Getting started with WebGL | Learning WebGL WebGL examples webglsamples – Project Hosting on Google Code [...]

  24. Nardon says:

    I am having some issues running WebGL on Linux for some reason.. >.>

    It first worked beautifully. Installed the latest driver (11.2) because I had some rendering issues (flickering graphics) with most demo’s but when I done that everything worked fantastic! But now WebGL doesn’t work anymore!

    Think it’s caused with the latest kernel update as it broke my driver already (had to reïnstall it) but the strange thing is that other OpenGL stuff like Amnesia: The Dark Descent still works great so the drivers work correctly.. :/

    Anyone knows what could be the issue?

  25. giles says:

    Are you using Firefox? It might be that they’ve added your graphics driver to their blacklist… Check it out here: https://wiki.mozilla.org/Blocklisting/Blocked_Graphics_Drivers

  26. Sokar says:

    really great tutorials, they are a great help to understand the basics of WebGL.
    But I’ve got a problem with your examples and lessons. If I start them from your webpage (e.g. http://learningwebgl.com/lessons/lesson05/index.html ) they work fine. But when I download the source to my computer and try to run it from my hdd, I only get a white page with the links back to your page. I’ve tried in Chrome and Iron (http://www.srware.net/software_srware_iron.php – Chromium Implementation) and both have the same problem. I’ve tried the latest stable Firefox too, but I couldn’t get it running in the first place, failed to initialize WebGL. Worked with the FF4 Betas, so I’ve probably try some newer Betas.

  27. Jonas Antunes da Silva says:

    for those having trouble with ATI GPU and chrome version 10+, try using the following parameter: –ignore-gpu-blacklist. It worked for me on Ubuntu 11.04 Beta 2 with chrome 10.0.648.205

  28. giles says:

    @Sokar — are you sure you’ve downloaded all of the dependencies, eg. glMatrix-0.9.5.min.js and webgl-utils.js? Is there anything in the error console?

    @Jonas — thanks! I’ll add that to the troubleshooting.

  29. Sokar says:

    @giles: I just downloaded the whole repository from github, just to make sure I’ve got everything. It works now, seems like in example 5 the texture for the cube was incorrect (it was a text/html-file instead of a graphic, dont’t how I got it…). But it seems to work now =)

  30. [...] GL implementation. But as of r645, that’s fixed. That version’s built into the current nightly Chromium builds, and I’m sure Mozilla won’t be far behind, at least for Firefox 6 (coming soon!) [...]

  31. cup says:

    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.

  32. giles says:

    @Sokar — ah, I see. Some browsers do weird stuff when saving web pages, perhaps that’s what happened there?

    @cup — not that incomplete as compared to 1.0 of the spec, but it’s an evolving standard and newer stuff does keep coming along.

  33. [...] 下图就是本课运行在一个支持WebGL浏览器上的结果: 单击这里,然后你就可以看到网页WebGL版本, 前提是你已经有一个支持WebGL的浏览器。如果你没有的话,这篇文章介绍了如何获得一个支持WebGL的浏览器。下面介绍它具体是如何运行的… [...]

  34. [...] tienes DirectX instalado — puedes descargarlo aquí. Una vez lo tengas en tu equipo, instala  Firefox o Chromium, el que más rabia te [...]

  35. not going in the new version of firefox

  36. [...] Learning WebGL: Lesson 0: Getting started with WebGL [...]

  37. krm says:

    I have done a sphere using J3DI using WIN 7 as OS and the graphic card is Nvidia Geforce GT330 M.

    the sphere appears correctly. but when I try to make a texture on it the sphere
    to became like this image:

    but unfortunately the sphere becomes as a squire like this :

    in addition, the shader I have used is this:

    uniform mat4 u_modelViewProjMatrix;
    uniform mat4 u_normalMatrix;
    uniform vec3 lightDir;

    attribute vec3 vNormal;
    attribute vec4 vTexCoord;
    attribute vec4 vPosition;

    varying float v_Dot;
    varying vec2 v_texCoord;

    void main()
    gl_Position = u_modelViewProjMatrix * vPosition;
    v_texCoord = vTexCoord.st;
    vec4 transNormal = u_normalMatrix * vec4(vNormal, 1);
    v_Dot = max(dot(normalize(transNormal.xyz), normalize(lightDir)), 0.3);

    #ifdef GL_ES
    precision highp float;
    uniform sampler2D sampler2d;

    varying float v_Dot;
    varying vec2 v_texCoord;

    void main()
    vec2 texCoord = vec2(v_texCoord.s, v_texCoord.t);
    vec4 color = texture2D(sampler2d, texCoord);
    color += vec4(0.1, 0.1, 0.1, 1);
    gl_FragColor = vec4(color.xyz * v_Dot, color.a);

    Can any one help me solving this problem please.

  38. krm says:

    sorry there are lots of mistakes in the previous comment. So, this is a correction.

    I have done a sphere using J3DI under WIN 7 as OS
    and Nvidia Geforce GT330 M as graphic card .

    the sphere appears correctly. but when I try to make a texture
    as what appears in this image:

    the sphere becomes as a squire like this :

  39. Blah says:

    Mac OS X 10.7 has WebGL built into Safari.

    Enable the developer menu and there is an option for Enable WebGL (turned off by default), so you don’t need Webkit nightlies and you don’t need to run terminal commands to enable it.

    Safari is catching up!

  40. [...] For best performance you should use Google Chrome. It supports WebGL as well as rendering to floating point textures. Firefox should provide the same visual results, but it is considerably slower since we basically have to render twice to achieve the same precision. If you are using Internet Explorer, you are out of luck. Detailed information on how to get WebGL working on different systems can be found here. [...]

  41. Your link to the continous integration site from chromium on mac is broken, here’s the new one:

  42. [...] problemas, quizás tu ordenador no tenga una tarjeta gráfica con las características necesarias. En esta página te dan una serie de trucos para que vea este tipo de páginas, algo complicados pero quizás te merezcan la [...]

  43. [...] 如果成功了,你可以在这里找到一个脚本,来避免每次重复的输入。 [...]

  44. Daniele says:

    the continuous integration page for getting the chrome-mac.zip is moved here:


  45. Nardon says:

    Alright, I just found out a way to get WebGL working on Linux with Google Chrome. So as it turned out, Google blacklisted all Linux Drivers, except for the official nVidia Drivers. Newer ATI drivers however, work just as good though, so you can try to start Chrome with the –ignore-gpu-blacklist parameter. This will avoid the driver check and allow you to run WebGL content normally.

    Firefox 6 and above whitelisted most newer ATI drivers for Linux so you should be able to use WebGL with this browser.

  46. giles says:

    @Daniele, @Philip — only just saw this, thanks for letting me know.

    @Nardon — thanks for the update, that’s useful too.

    I’ve updated the page appropriately.

  47. Georgi says:

    Hi, the command for Chromium is ./chrome not ./chromium.

    In this part /original/:
    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:

    –> ./chromium <–

    Next, click here to try out some WebGL pages.

  48. giles says:

    Thanks! I’ve updated the text as you suggest.

  49. Eli Mitchell says:

    Opera 12 alpha also has WebGL support. It is kinda buggy, but if you use it you can help Opera Developers by reporting the bugs with your particular graphics card. http://my.opera.com/desktopteam/blog/2011/10/13/introducing-opera-12-alpha

Leave a Reply

Subscribe to RSS Feed Follow Learning WebGL on Twitter