- Why GraalVM?
- Getting Started
- Release Notes
- Reference Manual
- GraalVM Updater
- JVM Languages Reference
- LLVM Languages Reference
- Python Reference
- R Reference
- Ruby Reference
- Scala Reference
- WebAssembly Reference
- Native Image
- Polyglot Reference
- Embedding Reference
- User Documentation
- GraalVM as a Platform
- Security Guide
Some languages and plugins are not part of the GraalVM core distribution and must be downloaded and installed separately. These include:
- GraalVM Native Image – a technology to compile an application ahead-of-time into a binary that runs natively on the system. Note: The Native Image plugin is available as an Early Adopter technology in GraalVM Enterprise. In GraalVM Community Native Image is distributed under the GPL 2 with Classpath Exception license.
- LLVM toolchain – a set of tools and APIs for compiling native programs to bitcode that can be executed with the GraalVM LLVM runtime.
- Python interpreter – a Python 3.7 compliant implementation.
- Ruby interpreter – an implementation of the Ruby 2.6.5 programming language.
- R interpreter – a GNU R 3.6.1 compatible implementation of the R programming language.
- GraalWasm – the WebAssembly (Wasm) language interpreter to run Wasm programs in the binary format.
Note: Python, R, Ruby and Wasm are experimental and not recommended for production use at this time.
To assist you with the installation, these features are pre-packaged as
components. The GraalVM installation contains the GraalVM Updater
gu, that can be used to manage components. GraalVM Updater also
verifies whether the version of the component is appropriate for your GraalVM
installation. Component packages are released for each GraalVM release with
respective updates. Component packages downloaded for previous release(s) cannot
be used with newer ones.
To deploy the installer tool, confirm that GraalVM is set in your
PATH environment variable.
There is a command-line help available.
gu -h to get commands overview.
gu <command> -h to get help specific for the particular command, for example
gu install -h.
A component may depend on requiring other components for its operation. GraalVM Updater verifies such requirements and will attempt to download the required dependencies, or abort the installation if component’s requirements are not met.
Note: Components intended for GraalVM Enterprise Edition can not be installed into GraalVM Community Edition.
Component Installation Modes #
Three modes of components installation are supported:
Depending on the GraalVM distribution, you download a component package from GitHub or Oracle Technology Network and GraalVM Updater will install it. The following pre-built packages are at your disposal:
With the already downloaded component JAR file, the component can be installed as
gu -L install component.jar
-L option, equivalent to
--file, tells to install
from the downloaded component archive. However, a component may depend on other
components (e.g., Ruby language depends on the LLVM toolchain). For example,
-L install component.jar will fail if the required components are not yet
installed. If you download all the dependencies into the same directory, you may
gu -L install -D
gu --help or
gu -C (see below) how to instruct GraalVM Updater to find and process required components as well.
Installation from Catalog
There is a component catalog on GitHub maintained by Oracle, from which you can install a component just by its name. GraalVM Updater first downloads the list of components, then uses the information in the list to download the actual component package and installs it.
To get a list of components available in the catalog, their IDs, and descriptive names, use
ComponentId, for example
ruby, can be used as:
gu install ruby
If you want to see more verbose messages during installation, you may use the
--verbose switch to see the download progress bar and verbose messages.
If a component being installed requires other components to be present, GraalVM Updater will search the Catalog to find the appropriate component and install it as well. If required components could not be found, installation will fail.
When using custom catalog URLs, it is possible, as a convenience, to set
GRAALVM_CATALOG pointing to the custom catalog’s URL.
GraalVM updater will use URL defined by
GRAALVM_CATALOG in preference to
the builtin ones. You may setup the environment variable in startup or profile
Note, for GraalVM Enterprise Edition users, components should be obtained from Oracle Technology Network which requires a manual installation to prevent the use of a “community” component version except for the R language and LLVM toolchain components which are available only from GitHub catalog.
Installation from Local Components Collection
Components can be downloaded manually in advance to a local file folder, or to a folder shared on the local network. GraalVM Updater can then use that folder instead of the catalog:
gu install -C /path/to/downloads/directory <component name>
specifying the directory to use as components collection. It is possible to type
components names (like
ruby) instead of filenames. GraalVM Updater also
attempts to find required dependencies in the local component collection.
When installing components from the given directory, you can allow installing all components which have correct version number for the GraalVM core using wildcards:
./gu install -C ~/Download/Components/ *
gu install native* will install the
native-image component, or anything that starts with
Similar to the installation from catalog, the path to the directory that
contains local components collection can be defined in the
Installed on your machine components can be printed with:
Installation Configuration #
The installation command of GraalVM Updater accepts multiple options and parameters and allows this syntax:
gu install [-0cCfFiLnorsuvyxY] param [param ...]
where the acceptable options are:
-0, --dry-run: dry run, do not change anything
-c, --catalog: treat parameters as component IDs from the GraalVM components catalog. This is the default
-C, --custom-catalog <url>: use a specific catalog URL to locate components
-L, --local-file: treat parameters as local filenames of packaged components
-f, --force: force overwrite, bypass version checks
-i, --fail-existing: fail on an existing component
-n, --no-progress: do not display the downloading progress
-o, --overwrite: overwrite different files
-r, --replace: replace existing components
-s, --no-verify-jars: skip integrity verification of component archives
-u, --url: interpret parameters as URLs of packaged components
-v, --verbose: be verbose and print versions and dependency information
-x, --ignore: ignore failures
-y, --only-validate: do not install, just check compatibility and conflicting files
-Y, --validate-before: download, verify, check file conflicts before any disk change is made
The following are common options to GraalVM Updater:
-A, --auto-yes: say YES or ACCEPT to all questions
-c, --catalog: treat parameters as component IDs from catalog of GraalVM components. This is the default
-C, --custom-catalog <url>: use user-supplied catalog at URL
-e, --debug: debug and print stacktraces
-E, --no-catalog-errors: do not stop, if at least one catalog is working
-h, --help: print help
-L, --local-file, --file: treat parameters as local filenames of packaged components
-N, --non-interactive: non-interactive mode. Fail when input is required
--show-version: print version information and continue
-u, --url: interpret parameters as URLs of packaged components
-v, --verbose: be verbose. Prints versions and dependency info
--version: print version
Finally, customers using Oracle GraalVM Enterprise Edition might need to pass an additional verification step to login to Oracle components repository. GraalVM Updater provides options for that:
--public-key / -k <path>to set the path to a custom GPG public key path
--username/-Uto enter a username
Rebuilding Images #
GraalVM components used to create guest language implementations may change over time, requiring a Native Image to be rebuilt. Polyglot native image and polyglot native C library may be out of sync, particularly:
- new languages may not be accessible;
- removed languages may cause the native binary to fail on missing resources or libraries.
To rebuild and refresh the native binaries, use the following command:
gu rebuild-images [--verbose] polyglot|libpolyglot|js|llvm|python|ruby [custom native-image args]
Components may be uninstalled from the GraalVM environment when no longer needed.
To uninstall a specific component you need to know its
ComponentId, which can be
r and so on.
The command to uninstall the component is:
gu remove ComponentId
If more components end with, for example,
ruby, the installer will print an
error message that you need to use component’s full names (
The uninstallation removes the files created during the installation. If a file
belongs to multiple components, it will be removed when the last component using
it is removed.
If GraalVM Updater needs to reach the component catalog, or download a
component package, it may need to pass through the HTTP proxy, if your network
uses one. On macOS, the proxy settings are automatically obtained from the OS.
On Linux, you must ensure that the
variables are set appropriately before you launch
gu. Please refer to your
distribution and/or desktop environment documentation for the details.
Sometimes, an intermediate (e.g., corporate) proxy may act as
“man-in-the-middle”, intercepting https-secured communication and issuing its
own host certificates, which cannot be verified by GraalVM Updater. If you see
error messages with descriptions containing
SunCertPathBuilderException, it is obviously the culprit.
GraalVM Updater intentionally does not support an option to disable certificate or hostname verification, for security reasons. You may try to add your proxy’s certificate to the GraalVM default security trust store (see JDK documentation for the details).
Working without Internet Access #
If your machine cannot access and download Catalog and GraalVM components from the Internet, either because it is behind a proxy, or for security reasons, Graal Updater can install components from a local directory, or a directory on a network share accessible on the target machine.
You need to prepare a directory, download all Components that you want to install and their dependencies (in case they require other GraalVM Components to work) into that directory.
Then you can use
gu -L install /path/to/file (where
-L option instructs to use local files,
equivalent to –local-file or –file). Adding
-D option will instruct Graal Updater
to look for potential dependencies in the directory next to the
installable file. Additionally,
gu -C /path/to/download/dir install component can be used, the specified
directory contents acting as a Catalog of components.
Note that with
gu -L you need to specify the component’s file name, while
gu -C <dir>, the component name must be used:
# Specify file location gu -LD install /tmp/installables/fastr.jar # Specify component name gu -C /tmp/instalables install r
Replacing Components and Files #
A component may be only installed once. GraalVM Updater refuses to install a
component if a component with the same
ComponentId is already installed. But the
installed component may be replaced. GraalVM Updater first uninstalls the
component and then installs a new package. To replace a component, use the
-r option. The
-L option, equivalent to
--local-file, tells to treat parameters as local filename of a packaged component.
gu install -L -r component.jar gu install -r ruby
The process is the same as if
gu remove is run first and
gu install next.
GraalVM Updater also refuses to overwrite existing files if the to-be-installed
and existing versions differ. There are cases when you may need to refresh file
contents, if they were modified or damaged. Use the
gu install -L -o component.jar gu install -o ruby
GraalVM Updater will just instruct to replace the contained files of a
component. By default, it will not alter anything. You can also use
--force) option, which disables most of the checks and allows you to install
If a language component is not installed running the code that tries to initialize the language context can result in an exception like this:
java.lang.ExceptionInInitializerError Caused by: com.oracle.truffle.polyglot.PolyglotIllegalArgumentException: A language with id '$language' is not installed. Installed languages are: [js, llvm].
If you see a problem like that, install the language component as explained on this page above.