Setting up an Eclipse installation for smooth upgrades

I’m going to admit that I like Eclipse. Maybe it’s an quirk of fate because it was the first well-featured modern IDE that I used, or maybe I just think the same way that the Eclipse guys and gals do. Whatever the reason I’ve invested quite a bit of time and effort understanding how Eclipse works and getting the most out of Eclipse. I’ve tried IntelliJ IDEA and I haven’t found it anywhere as nice to use as Eclipse. Most of my cow-orkers give me grief about it, oh well maybe I’ll try version 4.0 to see if CVS integration actually works.
Now, onto the real topic. Eclipse does have some interesting features in the way that the internal structure of the download is set up by default. What this means is that there is a lot of intermingling between the core libraries for Eclipse, the extra plugins that are installed by the developer, the configuration and customisation information and the workspace. So when upgrading Eclipse, you have the choice of trying to find out what bits have been changed, or just dumping the new version on top of the old version. After seeing the pain and suffering of Jason when he was doing this, I decided to find a better way.
To get the most out of Eclipse and the least pain for developers the best way to handle the setup is to partition all those components as best as Eclipse will let you. What follows is a process to follow during initial installation, and then for each upgrade.
Good luck !
This process works for me, it might not work for you.
If you trash your installation, your wife leaves you, your computer explodes or your camel gets fleas then it’s not my problem, don’t complain to me about it. When in doubt, make a backup. And even when you’re not in doubt make a backup. You have been warned.

NB: This process is for Windows, and it has worked under Windows 2k and XP. Anybody using a Unix variant should be smart enough to convert it to their needs. If you’re not, then re-install Windows.


To separate the directories that are used by Eclipse, create the following directories.
Step 1: Create the directories
c:\eclipse (unpack Eclipse zip file to here)
c:\eclipse_local (this will hold “local” plugins)
c:\eclipse_work (this holds the metadata directory)
Step 2: Create the link to the local plugins
To get Eclipse to notice the eclipse_local directory, create a file (and the associated subdirectory shown below). You’ll need to create this directory (or copy it from an old version) each time you upgrade as the Eclipse root directory is freshly created
c:\eclipse\links\.link containing the following single line: path=c:\\eclipse_local
Now, create the directories:
c:\eclipse_local\eclipse\features (this will hold local features)
c:\eclipse_local\eclipse\plugins (this will hold local plugins)
This is where to put the “non-core” Eclipse plugins (and features). These are the plugins that are added to your environment for development that are supplementary to what Eclipse provides. Currently I have things like checkstyle, profiler, dbedit and simian in my local plugins and nothing in my local features.
Step 3: Create the runtime shortcut
The final step is to create a shortcut for Eclipse to use the c:\eclipse_work directory. This is very important, or you will lose all your key shortcuts, and any other customisation that you make when you upgrade.
The shortcut information should have in the “Target:” field the following C:\eclipse\eclipse.exe -data c:\eclipse_work Pay attention to the “-data” option in the target. Now run Eclipse using this shortcut.
These three steps only need to be done once. It’s a bit of setup, but well worth it in the end.


This is where all the separation of directories pays off. I have been upgrading Eclipse from a nasty 2.1 installation to the current 3.0 M7 with minimal hassles. The sorts of things that have caused grief has been the changes in plugin compatibility (which means just upgrading the local plugins) and compatibility with the keybindings which seemed to change every second Milestone build. Yes, it was a hassle redoing my Emacs keybindings every 2 versions, but hopefully that will be fixed soon. I noticed that later releases allow the export and import of keybindings which will help.
Step 1: Rename the old version
This is fairly easy. Just rename c:\eclipse to c:\eclipse_{$version} (such as c:\eclipse_m2). This saves the old version should anything bad happen, or the version is just too buggy to use and you want to easily go back to a previous version.
Step 2: Unpack the new version
Unpack the new version to c:\eclipse. This will create a new directory structure where the old version was located. This is important because we are using basically a fresh install each time.
Step 3:Recreate the Links directory
Either create the links directory as shown in step 2 of the installation instructions, or just copy the links directory from the old version. I’ve been copying the directory from previous versions without any hassles.
Step 4. Run Eclipse using the shortcut.
This will still display the “running post-install” text that occurs when you install Eclipse for the first time. I’ve had Eclipse complain about workspace/perspective corruption when I run it for this time.
I’ve just shut down Eclipse and restarted with no other changes and it works perfectly.


9 thoughts on “Setting up an Eclipse installation for smooth upgrades

  1. You can also set up a local Eclipse upgrade server; this works a lot better now that 3.0M7 has promised to preserve compatability.
    The upgrade server will solve restoring your plugins for you, as well as allowing you to share plugins with others. Between that and keeping a workspace separate from the installation, you can easily get past most upgrade headaches.
    (Speaking as someone who’s been following the latest Eclipse milestones solidly since 3.0M1)

  2. Eclipse Update servers

    Jon Eaves of Thoughtworks was writing on managing Eclipse updates and how to preserve your environment between upgrades.
    While this was an excellent guide to preserving your own environment, there’s a better way if you need to do this at a team o

  3. John, I came with pretty much the same scenario, except that I have more then one workspace. It works perfectly for me.

  4. It looks like the eclipse_local directory has to be on the root. If I do something like c:\dir1\dir2\eclipse_local, eclipse can’t find them. Am I missing anything? Thanks.

  5. Re: my comments on Oct 30 rgd c:\dir1\dir2\eclipse_local
    On Windows I actually had to use double slashes to get it work, something like c:\\dir1\\dir2\\eclipse_local

  6. Hi guys,
    I got a question regarding Eclipse, maybe you can help me: how to run Eclipse and specify some plugin to integrate? I need to debug an Eclipse plugin from different IDE, so I don’t have a PDE… Usually it’s simple to figure out, but Eclipse tools tends to not show what are they actually doing at console :(( I guess there should be some command line option…

  7. Hi,
    i had a go at this but ran into problems:
    1. Windows doesnt like you creating a file which start with a ‘.’. It thinks you’ve missed the name and the extension is ‘link’. In the end, I had to use cygwin to create the file.
    2. When I try and run eclipse I get:
    !SESSION Mon Feb 20 16:01:26 GMT 2006 ——————————————
    !ENTRY org.eclipse.core.launcher 4 0 2006-02-20 16:01:26.156
    !MESSAGE Exception launching the Eclipse Platform:
    java.lang.RuntimeException: Could not find framework
    at org.eclipse.core.launcher.Main.getBootPath(
    at org.eclipse.core.launcher.Main.basicRun(
    at org.eclipse.core.launcher.Main.main(
    Now perhaps the guide was for new installs? I have an existing eclipse install I like.
    Any idea whats wrong? I am running with 3.2.

Comments are closed.