goreleaser/www/docs/customization/upx.md

UPX

Since: v1.18

Having small binary sizes are important, and Go is known for generating rather big binaries.

GoReleaser has had -s -w as default ldflags since the beginning, which help shaving off some bytes, but if you want to shave it even more, upx is the de facto tool for the job.

GoReleaser has been able to integrate with it via custom build hooks, and now UPX has its own configuration section:

!!! warning "Compatibility"

`upx` does not support all platforms! Make sure to check
[their issues][upx-issues] and to test your packed binaries.

Namely, _macOS Ventura_ is not supported at the moment.

# .goreleaser.yaml
upx:
  - # Whether to enable it or not.
    #
    # Templates: allowed (since v1.21)
    enabled: true

    # Filter by build ID.
    ids: [build1, build2]

    # Filter by GOOS.
    #
    # Since: v1.19
    goos: [linux, darwin]

    # Filter by GOARCH.
    #
    # Since: v1.19
    goarch: [arm, amd64]

    # Filter by GOARM.
    #
    # Since: v1.19
    goarm: [8]

    # Filter by GOAMD64.
    #
    # Since: v1.19
    goamd64: [v1]

    # Compress argument.
    # Valid options are from '1' (faster) to '9' (better), and 'best'.
    compress: best

    # Whether to try LZMA (slower).
    lzma: true

    # Whether to try all methods and filters (slow).
    brute: true

!!! info

If `upx` is not in `$PATH`, GoReleaser will automatically avoid running it.

Notice you can define multiple upx definitions, filtering by various fields. You can use that to have different compression options depending on the target OS, for instance - or even to run it only on a few selected platforms.

!!! tip

Learn more about the [name template engine](templates.md).