Back to Guides

Upx

Ultimate Packer for eXecutables (UPX) is a compression tool reducing the size of executables. Quarkus can compress the produced native executable to reduce its size. Such compression is interesting when:

  • building CLI tools, and you want to reduce the disk footprint,

  • building small container images.

Note that UPX compression:

  1. increases your build time, mainly if you use high-compression levels

  2. increases the startup RSS usage of the application

System vs. Container

The UPX compression requires:

  • the upx command to be available in the system PATH;

  • or to have built the native executable using an in-container build.

If you have the upx command available on your path, Quarkus uses it. Otherwise, if you built the native image using an in-container build (using quarkus.native.container-build=true) and if the builder image provides the upx command, Quarkus compresses the executable from inside the container.

If you are not in one of these cases, the compression fails.

upx is cross-platform.

upx can compress executables using a different architecture and OS than your host machine. For example, upx on a macOS machine can compress a Linux 64-bits executables.

Configuring the UPX compression

Then, in your application configuration, enable the compression by configuring the compression level you want:

quarkus.native.compression.level=5

If the compression level is not set, the compression is disabled. The compression will happen once the native executable is built and will replace the executable.

Compression level

The compression level goes from 1 to 10:

  • 1: faster compression

  • 9: better compression

  • 10: best compression (can be slow for big files)

Extra parameters

You can pass extra parameter to upx, such as --brute or --ultra-brute using the quarkus.native.compression.additional-args parameter. The value is a comma-separated list of arguments:

quarkus.native.compression.level=3
quarkus.native.compression.additional-args=--ultra-brute,-v

The exhaustive list of parameters can be found in the UPX documentation.