upx: Usage, Options & Common CI Errors

upx packs an executable so it self-decompresses at launch, shrinking the artifact.

upx makes a binary dramatically smaller for distribution. The CI cautions are that it is not idempotent (re-packing errors), it can confuse antivirus/EDR, and it strips the ability to inspect the unpacked binary with normal tools.

What it does

upx (Ultimate Packer for eXecutables) compresses an executable in place, wrapping it with a small stub that decompresses it into memory at startup. The packed binary runs identically but is much smaller on disk.

Common usage

Terminal

upx app                            # compress (default level)
upx --best app                     # maximum compression
upx -9 --lzma app                  # strongest ratio
upx -d app                         # decompress back
upx -t app                         # test integrity

Options

Flag	What it does
-1 .. -9	Compression level (fast .. best)
--best --lzma	Maximum ratio (slower)
-d	Decompress / unpack
-t	Test a packed file
-o <file>	Write output to a new file

Common errors in CI

"CantPackException: already packed by UPX" - upx is not idempotent; guard the step or run upx -d first if re-running. Packed binaries frequently trip antivirus/EDR heuristics, so a packed CI artifact may be quarantined on download. Packing breaks tools that read the on-disk ELF (gdb symbols, addr2line) and is incompatible with some hardened/static binaries (Go binaries can break at certain versions) - keep an unpacked copy for debugging.