How to launch Eclipse Theia

September 25, 2019 | 9 min Read

In this article we provide an overview on how to get started with Eclipse Theia. More precisely, we will describe how to easily install and launch your own instance. In case you wonder what Eclipse Theia is, please see this blog post for an introduction and this FAQ about Eclipse Theia. In this article, we answer a very simple question:

How to install/launch/run Eclipse Theia to use it as an IDE for development?

There are several ways to launch/run Theia, so when getting started, this can already be a confusing question. There are two things you should be aware of, especially, if you are new to Eclipse Theia. First, Theia itself is actually a platform to build tools. So you cannot strictly “launch Theia”, but you can launch products, which are based on Theia. This sounds more complicated than it actually is when you look at the options below. If you want to learn more about what “Theia is a platform” means, please have a look at this comparison between Eclipse Theia and VS Code. Second, Theia-based products can be deployed in the cloud and accessed as browser applications, but also be deployed as desktop applications (using electron).

We’ll describe seven options on how to launch products based on Theia below, whereas option 0, 4, 5 and 6 are the fastest in case you just want to try it out. We will highlight the benefits of every option in the respective section.

[Option 0: Download and launch the Theia Blueprint](#option 0) [Option 1: Launch it from a package.json (plain and simple)](#option 1) [Option 2: Use the preconfigured docker image (‘cause container are great)](#option 2) [Option 3: Clone, build and run from the sources (for contributors)](#option 3) [Option 4: Use Eclipse Che (to host runtimes and workspaces)](#option 4) [Option 5: Use Gitpod](#option 5) [Option 6: Try online in an example tool based on Eclipse Theia](#option 6)

Please note that this article is meant to be an overview, so we won’t go into too much detail, but will will link existing technical documentation for detailed instructions in the corresponding sections in case you want to explore even further. If you are a seasoned web developer who knows how to build and launch web applications, in particular node.js applications, many of the following steps will be pretty familiar to you. If you have not used node.js yet, you are new to Theia and would like to try it out, this blog post should help you in your first steps.

Option 0: Download and launch the Theia Blueprint

If you are interested in trying Theia on the desktop, this is the way to go. The Theia project provides a template desktop product called Eclipse Theia Blueprint. It comes with installers for all major operating systems so it is very easy to consume. Theia blueprint is assembling a subset of existing Eclipse Theia features and extensions and a good way to showcase the abilities of the platform. Furthermore, there is documentation on how to use Theia blueprint as a basis for defining your own custom product based on Theia.

Option 1: Launch it from a package.json (plain and simple)

As Eclipse Theia and its extensions are node.js packages and a Theia application is collection of packages, one very simple way to launch Theia plus selected extensions is to create a package.json listing all extensions you want to include and launch this using CLI. This essentially means you define your own product based on Theia and directly start it. The Theia documentation provides a blueprint for such a product package.json (see the Theia documentation). After installing the dependencies by simply running yarn in your Theia application package and building it by invoking the Theia CLI, you can directly launch Theia from the command line and access it in the browser. The advantage of this way of launching Theia is that it is very simple and does not require more than yarn and npm. It also allows to very easily add and remove extensions (see this article on how to customize Eclipse Theia for further details).

Option 2: Use the preconfigured docker image (‘cause container are great)

Option 1 requires you to have npm and yarn installed on your local machine so that you can download all Theia extensions, including their dependencies, and build your Theia product. Certain Theia extensions, however, might have specific, additional system requirements, such as compilers or language servers, that need to be installed in your OS. While the system requirements of the example linked in option 1 are likely available on most developer machines, this might not be the case for more “exotic” extensions of Theia, such as Rust or Go support. Further, if you want to launch Theia on a server, you might prefer to have it encapsulated in a container.

To launch Theia using docker, you find a list of preconfigured images on github. As you can see, those preconfigured images target specific use cases, e.g. Python or Ruby development. Please note that there is a package.json defining a Theia-based product for each of those images (browse into them on GitHub), which shows you the extensions that are included in the image and allow you to further customize the Theia version. If you are unsure, which image to try, the most famous one at the moment is definitely the Theia IDE for web developers.

Option 3: Clone, build and run from the sources (for contributors)

This option is again very similar to option 1, but instead of getting the npm packages that Eclipse Theia consists of from the package registry (, they will be directly built from the sources. All necessary steps to do so are described on github. Please note that you still need a package.json, which defines which modules are in the launched product. There are two examples for such configurations provided within the Theia repository (see on github): one for a browser application and a second one for a desktop application based on Electron. If you had a look at Option 1, you will see that more modules are listed in this example package.json.

The required effort and complexity to launch Theia this way is very similar to option 1, as the sources and the build in Theia is very well maintained. The benefit is that you can now modify the original sources of Theia and immediately see any changes you apply. So this option is interesting, if you want to have a deeper look at the internals of Theia and of course if you want to extend/fix and contribute something.

Option 4: Use Eclipse Che (to host runtimes and workspaces)

If you do not want to download, deploy or compile anything, but you just want to try Eclipse Theia in a hosted way, you can use Eclipse Che to do so. In a nutshell, Eclipse Che provides a workspace server, meaning a server, which can host the development environment of one or several developers. If you move your development environment to the cloud, you will either need to set up those developer runtimes yourself, or use something like Eclipse Che. Please see this article on the relationship between Eclipse Theia and Eclipse Che.

Eclipse Theia is the default IDE (called “editor” in Che) for Che starting with version 7. That means, Che defines a IDE product based on Theia (called Che-Theia). The simplest way to use Theia in Che is to create an account (see here on how to create an openshift Che test account) go to dashboard and either:

  • Select a preconfigured stack which mentions “Eclipse Theia”
  • Create any other stack, go to its configurations and select “Theia” as an editor (on the respective tab).

In case you want to try Eclipse Che and Eclipse Theia in combination running on your own premises or cloud services, please follow this guide on how to install and run Eclipse Che.

Option 5: Use Gitpod

Gitpod is another solution to host online workspaces including a browser IDE based on Theia. It was one of the first products adopting Theia. Gitpod has a very streamlined workflow, allowing you to describe the required development environment as a script. Based on this, Gitpod will set-up a fresh development environment including the Theia IDE in an amazingly short time. It can even pre build projects to get you ready to code with almost no waiting time. The concept behind this is to enable a fresh working environment for every task you start. Gitpod has been published as an open source project in 2020 while some advanced features remain only available in the commercial version. Gitpod can be self-hosted, but it also offers online workspaces SaaS, which can be used for free within some limits.

If a Git repository of a project contains a Github script describing the necessary development environment, you can start to code on this project with Theia by just entering{YourRepoURL}. As the Theia open source project provide such a config, you can for example start to code on Theia project using the Theia IDE in Gitpod by opening in your browser.

Option 6: Try online in an example tool based on Eclipse Theia

The coffee editor example is a showcase how to build domain-specific tools based on Theia. It includes a variety of features besides code editing such as a diagram editor (based on Eclipse GLSP), a textual DSL (based on Eclipse Xtext), a tree editor (based on and JSON Forms), a code generator (based on Xtend), a data analysis and many more. The coffee editor demonstrates how flexible you can build domain-specific tools using Theia. Also it shows how several tool technologies integrate well, such as GLSP for diagram editors. The coffee editor can be tried out online. Furthermore, as it is part of the open source project, all underlying sources are available, so you can use it as a blueprint for your own tools based on Eclipse Theia. Visit the website to learn more about it!

Conclusion and more

In this article, we have described four options on how to run Eclipse Theia, but this list is not complete. There are commercial offerings providing Theia hosting as a service. Furthermore, Eclipse Theia is used as a basis for implementing domain- and vendor-specific tools. So soon you might find a customized Theia version as a tool offering by any vendor which provides a custom tool. If you are interested in using Eclipse Theia to create your own tool or to migrate an existing tool to the cloud, have a look at our service offering for support around Eclipse Theia, web-based tools or tools in general and please get in contact with us!

Finally, if you are interested in a quick guide on how to use Eclipse Theia, how to customize and extend it, please follow us on Twitter, we will publish the next parts of this article series soon.

Jonas, Maximilian & Philip

Jonas Helming, Maximilian Koegel and Philip Langer co-lead EclipseSource. They work as consultants and software engineers for building web-based and desktop-based tools. …