Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
eclipse.ini
Contents
Overview
Eclipse startup is controlled by the options in $ECLIPSE_HOME/eclipse.ini
. If $ECLIPSE_HOME
is not defined, the default eclipse.ini
in your Eclipse installation directory (or in the case of Mac, the Eclipse.app/Contents/MacOS
directory) is used.
eclipse.ini
is a text file containing command-line options that are added to the command line used when Eclipse is started up. There are many options available, please see here.
Important:
- You can, and should, experiment with changes to the launch command from your Command Prompt/Terminal before changing the
eclipse.ini
itself. - Each option and each argument to an option must be on its own line.
- All lines after
-vmargs
are passed as arguments to the JVM, so all arguments and options for eclipse must be specified before-vmargs
(just like when you use arguments on the command-line) - Any use of
-vmargs
on the command-line replaces all-vmargs
settings in the .ini file unless--launcher.appendVmargs
is specified either in the .ini file or on the command-line. (doc) - -XX VM arguments are subject to change without notice, even during minor updates. If the JVM keeps exiting with code 2 instead of starting Eclipse, try removing them.
- Make a backup--keep a copy of the original contents on hand so you don't break your installation and have to download it all again.
By default, eclipse.ini
looks something like this (the exact contents will vary based on operating system and which Eclipse package you have):
-startup ../../../plugins/org.eclipse.equinox.launcher_1.2.0.v20110502.jar --launcher.library ../../../plugins/org.eclipse.equinox.launcher.cocoa.macosx.x86_64_1.1.100.v20110502 -product org.eclipse.epp.package.jee.product --launcher.defaultAction openFile -showsplash org.eclipse.platform --launcher.XXMaxPermSize 256m --launcher.defaultAction openFile -vmargs -Dosgi.requiredJavaVersion=1.5 -XX:MaxPermSize=256m -Xms40m -Xmx512m
Among other things, this sets the heap space to 40MB initially and a maximum of 512MB, and also specifies a maximum PermGen size of 256MB. A max heap of 512MB might be OK for some users, but it's often necessary to bump that value up for large project sets or when some third-party plugins are installed.
Specifying the JVM
One of the most recommended options to use is to specify a specific JVM for Eclipse to run on. Doing this ensures that you are absolutely certain which JVM Eclipse will run in and insulates you from system changes that can alter the "default" JVM for your system. Many a user has been tripped up because they thought they knew what JVM would be used by default, but they thought wrong. eclipse.ini lets you be CERTAIN.
The following examples of eclipse.ini
demonstrate correct usage of the -vm option.
Note the format of the -vm
option - it is important to be exact:
- The
-vm
option and its value (the path) must be on separate lines.
TODO: I know this next statement is not completely true, I just don't know the exact answer. A path ending in "bin", pointing to the "bin" directory of the Java distro works, and Ed Merks tells me that pointing to a "shared library" works also.
- The value must be the full absolute or relative path to the Java executable, not just to the Java home directory.
- The
-vm
option must occur after the other Eclipse-specific options (such as-product
,--launcher.*
, etc), but before the-vmargs
option, since everything after-vmargs
is passed directly to the JVM. - For the 32-bit Eclipse executable (eclipse.exe on Windows) a 32-bit JVM must be used and for the 64-bit Eclipse executable a 64-bit JVM must be used. 32-bit Eclipse will not work with a 64-bit JVM.
Here is an example of what eclipse.ini
might look like on a Windows system after you've added the -vm
argument and increased the maximum heap space:
-startup plugins/org.eclipse.equinox.launcher_1.2.0.v20110502.jar --launcher.library plugins/org.eclipse.equinox.launcher.win32.win32.x86_1.1.100.v20110502 -product org.eclipse.epp.package.java.product --launcher.defaultAction openFile --launcher.XXMaxPermSize 256M -showsplash org.eclipse.platform --launcher.XXMaxPermSize 256m --launcher.defaultAction openFile -vm C:\Java\JDK\1.8\bin\javaw.exe -vmargs -Dosgi.requiredJavaVersion=1.5 -Xms40m -Xmx1024m
Remember that the exact values will differ slightly depending on operating system and Eclipse package.
-vm value: Windows Example
This is how the -vm
argument might look on Windows (your exact path to javaw.exe
could be different, of course. Please beware of paths that contain a space, the examples below do not have any spaces, and using quotation marks around paths that contain spaces does not seem to work):
-vm C:\jdk1.7.0_21\bin\javaw.exe
Or
-vm C:\progra~1\Java\jre1.8.0_112\bin\javaw.exe
An alternative way is to insert the following VM option before the -vmargs option in the Eclipse shortcut's properties (edit the field Target inside the "Shortcut" tab):
-vm C:\jdk1.7.0_21\bin\javaw.exe
or
-vm C:\jdk1.7.0_21\jre\bin\java.exe
This might not work on all systems. If you encounter "Java was started but returned exit code=1" error while starting the eclipse, modify the -vm
argument to point to jvm.dll
(exact path could be different):
-vm C:\Development\Java\64bit\jdk1.7.0_09\jre\bin\server\jvm.dll
-vm value: Linux Example
This is how the -vm argument might look on Linux (your exact path to java
could be different, of course):
-vm /opt/sun-jdk-1.6.0.02/bin/java
-vm value: macOS Example
On a macOS system, you can find eclipse.ini
by right-clicking (or Ctrl+click) on the Eclipse executable in Finder, choose Show Package Contents, and then locate eclipse.ini
in the Eclipse
folder under Contents
. The path is often:
/Applications/Eclipse.app/Contents/Eclipse/eclipse.ini
For versions of Mac OS X 10.7+ is something like:
-vm /Library/Java/JavaVirtualMachines/<JRE_NAME>/Contents/Home/bin
For example, the latest JDK 1.8 (as of July 2015) is
/Library/Java/JavaVirtualMachines/jdk1.8.0_51.jdk/Contents/Home/bin
For standard Mac Java installations and so you don't have to continually update the setting when you install new Java VMs, set the -vm
flag to simply /usr/bin
:
-vm /usr/bin
If you want to use another JDK (that has the macOS directory layout, like the .tar.gz from AdoptOpenJDK) you should use:
-vm /<PATH_TO_YOUR_JDK>/Contents/Home/bin/java
For JDKs without macOS directory layout see: Using a JDK without macOS directory layout
NOTE: Occasionally, depending on the version of your macOS and whether or not you had already run this particular Eclipse installation before, upon launch after changing the -vm, you may run into an error that says "the application is damaged and can't be opened". This is the expected behavior since you just modified a signed/notarized app. This problem can be overcome by opening the Eclipse application once before changing the eclipse.ini file. Alternatively, running of the following command can fix the issue too: xattr -cr Eclipse.app
Here is additional information:
Perhaps the best way to determine the location for the JDK you want to use is with the utility
/usr/libexec/java_home --verbose
From the list produced by that command, select the JDK you want to use and put that path into the eclipse.ini file, making sure to append /bin/java
to the path (eg, /Library/Java/JavaVirtualMachines/jdk1.8.0_51.jdk/Contents/Home/bin/java
Note that the full path can either include java
or not. For example, the following will both work:
-vm /Library/Java/JavaVirtualMachines/jdk1.8.0_51.jdk/Contents/Home/bin
-vm /Library/Java/JavaVirtualMachines/jdk1.8.0_51.jdk/Contents/Home/bin/java
Using a JDK without macOS directory layout
If you want to use a JDK that doesn't follow the macOS directory layout, like the ones installed through SDKMAN!, then you need to specify the path to the libjli.dylib
file.
For JDK 11+: <JDK_11+_HOME>/lib/jli/libjli.dylib
For JDK 8: <JDK_8_HOME>/jre/lib/jli/libjli.dylib
Examples using SDKMAN!
JDK 11+
-vm /Users/<YOUR_USER>/.sdkman/candidates/java/11.0.8.hs-adpt/lib/jli/libjli.dylib
JDK 8
-vm /Users/<YOUR_USER>/.sdkman/candidates/java/8.0.265.hs-adpt/jre/lib/jli/libjli.dylib
NOTE: Beware that if you use current
instead of using a specific JDK version identifier it will use the default if you launch the Eclipse.app using the UI (double-click or using Spotlight). If you launch it from a terminal it will use the one currently selected.
See Also
- FAQ How do I run Eclipse?
- FAQ How do I increase the heap size available to Eclipse?
- FAQ How do I increase the permgen size available to Eclipse?
This FAQ was originally published in Official Eclipse 3.0 FAQs. Copyright 2004, Pearson Education, Inc. All rights reserved. This text is made available here under the terms of the Eclipse Public License v1.0.