- Why GraalVM?
- Getting Started
- Reference Manual
- GraalVM Updater
- Native Image
- Polyglot Reference
- Embedding Reference
- Truffle Language Implementation Framework
- JVM Languages Reference
- LLVM Languages Reference
- Python Reference
- R Reference Manual
- Ruby Reference
- WebAssembly Reference
- Debugging and Monitoring Tools
- GraalVM as a Platform
- Security Guide
- Release Notes
gu, is a command line utility available in the core
distribution of GraalVM, to install and manage additional components. These
- Native Image – a technology to compile an application ahead-of-time into a binary that runs natively on the system.
- 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 – an implementation of the Python 3.8.2 language.
- Ruby interpreter – an implementation of the Ruby 2.6.6 programming language.
- R interpreter – a GNU R 3.6.1 compatible implementation of the R programming language.
- GraalWasm – an implementation of the WebAssembly (Wasm) programming language.
These components must be downloaded and installed separately. To assist you with the installation, components are pre-packaged as JAR files. GraalVM Updater verifies whether the version of a component is appropriate for the current installation. Component packages are released for each GraalVM distribution with respective updates. Component packages downloaded for previous release(s) cannot be used with newer ones.
Note: Components intended for Oracle GraalVM Enterprise Edition cannot be installed to GraalVM Community Edition.
The source code of GraalVM Updater is located in the
folder. To deploy the tool, set the
PATH environment variable to
GraalVM_HOME/bin (see Getting Started).
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.
Component Installation #
Three modes of a component installation are supported:
Manual Installation #
Download a component package to your local machine. If you are a GraalVM Enterprise user, download a component package from the Oracle Technology Network page. The following pre-built components are available for download:
- Oracle GraalVM Enterprise Edition Native Image Early Adopter
- GraalVM LLVM Toolchain Plugin
- Oracle GraalVM Enterprise Edition Ruby Language Plugin
- Oracle GraalVM Enterprise Edition Python Language Plugin
- Oracle GraalVM Enterprise Edition WebAssembly Language Plugin
If you are a GraalVM Community user, download a component package from GitHub.
Having downloaded the component package in consideration of the operating system and the underlying Java SE version, install it with:
gu -L install component.jar
For example, to install the Native Image component for Java 11 GraalVM Enterprise distribution on macOS, run:
gu -L install native-image-installable-svm-java11-darwin-amd64-20.0.1.jar
-L option, equivalent to
--file, tells to install a component from a downloaded JAR.
However, a component may depend on other components (e.g., Ruby depends on the LLVM Toolchain plugin). For example,
-L install component.jar will fail if the required components are not yet
installed. If all dependencies are downloaded into the same directory, you can run:
gu -L install -D
gu --help or
gu -C how to instruct GraalVM Updater to find and process required components as well.
Note: Manual installation is required for Oracle GraalVM Enterprise Edition users.
Installation from Catalog #
There is a components catalog available on GitHub, maintained by Oracle, from which you can install a component 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.
Get a list of components available in the catalog, their IDs and descriptive names:
Install the component package using the
ComponentId value, for example
gu install ruby
If you want to see more verbose messages during installation, use the
If a component installation requires other component(s) to be pre-installed, GraalVM Updater will search the catalog to find an appropriate component and install it as well. If a required component cannot be found, installation will fail.
When using custom catalog URLs, it is possible, for 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: Installation from catalog is required for GraalVM Community users. For Oracle GraalVM Enterprise Edition users, components should be obtained from Oracle Technology Network which requires a manual installation. Except for the R language component which can be installed to GraalVM Enterprise only from GitHub:
gu install r
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 ComponentId
Specify the directory to use as components collection. It is possible to type
components names (like
ruby) instead of filenames. GraalVM Updater will also
attempt to find required dependencies in the local component collection.
When installing components from a given directory, you can allow installing all components which have correct version number using wildcards:
./gu install -C ~/Download/Components/ native*
It will install the
native-image component, or anything that starts with
Check Installed Components #
Installed on a machine components can be printed with:
A generic support R, Ruby, Python and WebAssembly languages will work out of the box in most cases. It is recommended to fine-tune system-dependent configurations, thus follow the recommendations in the component post-installation messages.
If a necessary component installed, check its version:
native-image --version llvm-toolchain --version ruby -v Rscript --version graalpython --version wasm --version
Already installed on components can be printed with:
Component Uninstallation #
Components may be uninstalled when no longer needed. To uninstall a specific component, use its
gu list to find out the exact
ComponentId. The command to uninstall the
gu remove ruby
If more components end with, for example,
ruby, the installer will print an
error message that a component full name is required (
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.
Rebuild Images #
A set of GraalVM components that provide language implementations may change. 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]
Installation Configuration #
The installation command of GraalVM Updater accepts multiple options and parameters and allows this syntax:
gu install [-0cCfFiLnorsuvyxY] param [param ...]
The following options are currently supported:
-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. Prints 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
GraalVM Updater Commands Overview #
There is a command-line help available by running
GraalVM Updater usage options:
gu info [-cClLnprstuvV] <param>: print the information about specific component (from file, URL or catalog)
gu available [-aClvV] <expr>: list components available in the catalog
gu install [-0cCDfFiLnorsuvyxY] <param>: install a component package
gu list [-clv] <expression>: list installed components or components from catalog
gu remove [-0Dfxv] <id>: uninstall a component
gu update [-cCnLsux] [<ver>] [<param>]: upgrade to the recent GraalVM
gu rebuild-images: Rebuild native images. Use
-hfor detailed usage
GraalVM Updater common options:
-A, --auto-yes: say YES or ACCEPT to a question
-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: enable debugging 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: enable 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: enable verbose output. Print versions and dependency information
--version: print version
Oracle GraalVM Enterprise Edition users might need to pass an additional verification step to login to Oracle components repository. GraalVM Updater tool provides options for that:
--public-key / -k <path>to set the path to a custom GPG public key path
--username/-Uto enter a username
--native: run using the native launcher with limited Java access (default)
--jvm: run on the Java Virtual Machine with Java access
--vm.[option]: pass options to the host VM. To see available options, use
--log.file=<String>: redirect guest languages logging into a given file
--log.[logger].level=<String>: set language log level to OFF, SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST or ALL
--help: print this help message
--help:vm: print options for the host VM
Configure Proxies #
If GraalVM Updater needs to reach the component catalog, or download a component
package, it may need to pass through the HTTP/HTTPS proxy, if the network uses one. On
macOS, the proxy settings are automatically obtained from the OS. On Linux,
ensure that the
https_proxy environment variables are set
appropriately before launching the
gu tool. Refer to the distribution
and/or desktop environment documentation for the details.
GraalVM Updater intentionally does not support an option to disable certificate
or hostname verification, for security reasons. A user may try to add proxy’s
certificate to the GraalVM default security trust store. A user can also
download the components manually to a folder, and then use
gu -L install
gu -C /path/to/download/dir install component to install
from a local filesystem.
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
Replace Components and Files #
A component may be only installed once. GraalVM Updater refuses to install a
component if a component with the same ID is already installed. But the
installed component may be replaced. GraalVM Updater first uninstalls the
component and then installs a new package. To replace component, use
option, and the
--file) option 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.
The GraalVM Updater also refuses to overwrite existing files if the
to-be-installed and existing versions differ. There are cases when refreshing
file contents may be needed, if they were modified or damaged. Use
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. Alternatively, use
--force) option, which disables most of the checks and allows 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.