# Compressing native executables using 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`;

- an explicitly defined `quarkus.native.compression.container-image`;

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

If `quarkus.native.compression.container-image` is not set explicitly, it will implicitly default to `quarkus.native.builder-image`.

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 compression image provides the `upx` command, Quarkus compresses the executable from inside the container.

If you want to force compression to take place in a container, you can set `quarkus.native.compression.container-build` to `true` (or `false` to explicitly not run compression in a container).

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

Setting `quarkus.native.compression.container-image` results in the compression to run in a container. If you want to set the variable, but not run the compression in a container, set `quakrus.native.compression.container-build` explicitly to `false`.

| `WORKDIR` for the image used for compression The executable to compress is mounted in directory `/project`. Since the container runs `upx` in the current working directory, the `WORKDIR` of the image used for compression must be `/project`.

Compression can be explicitly en-/disabled by setting `quarkus.native.compression.enabled`.

| 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.