Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow AI toolsbreadcrumb arrow gcx CLIbreadcrumb arrow Install gcx
Grafana Cloud Enterprise Open source

Install gcx

Quick install using the script

The fastest way to install gcx on Linux or macOS is with the script:

sh 
curl -fsSL https://raw.githubusercontent.com/grafana/gcx/main/scripts/install.sh | sh

The script:

  • Detects your operating system and architecture.
  • Downloads the latest release from GitHub
  • Verifies the SHA-256 checksum.
  • Installs the binary to ~/.local/bin.

Upgrade

To upgrade, run the same command again. The script always installs the latest release.

Check the result:

sh 
gcx --version

If the version does not change, refer to The version does not change after an upgrade.

Installer configuration options

Use these environment variables to customize the install script:

Environment variableDefaultDescription
GCX_INSTALL_DIR$HOME/.local/binDirectory to install the binary into
GCX_VERSIONlatestSpecific version to install (e.g., 0.2.4)
GITHUB_TOKENunsetGitHub token for API requests (avoids rate limits)

The script also accepts INSTALL_DIR and VERSION. The GCX_ names take precedence. Prefer the GCX_ names, because INSTALL_DIR and VERSION are common names, and curl | sh inherits every variable that your shell exports.

Examples

Install a specific version:

sh 
curl -fsSL https://raw.githubusercontent.com/grafana/gcx/main/scripts/install.sh | GCX_VERSION=0.2.4 sh

Install to /usr/local/bin:

sh 
curl -fsSL https://raw.githubusercontent.com/grafana/gcx/main/scripts/install.sh | GCX_INSTALL_DIR=/usr/local/bin sh

Uninstall

To remove gcx, delete the binary:

sh 
rm ~/.local/bin/gcx

Install gcx with Homebrew (macOS and Linux)

To install gcx with Homebrew run:

shell 
brew install gcx

This command installs the gcx formula from homebrew-core. Homebrew has a prebuilt bottle for macOS and Linux, so the install takes seconds. You do not need to add a tap.

To upgrade an existing installation:

shell 
brew upgrade gcx

Install from the Grafana tap

The Grafana tap also carries gcx. Use the tap if you want Homebrew to compile the binary on your machine:

shell 
brew install grafana/grafana/gcx

Homebrew installs go as a build dependency for this formula. The first install usually takes 30 to 60 seconds, and later upgrades reuse the Homebrew download cache.

Install gcx from one source only. Two Homebrew formulas with the same name conflict with each other.

Homebrew and macOS Gatekeeper

Both Homebrew methods avoid the macOS Gatekeeper problem. Homebrew does not set the quarantine attribute on the files that it installs, so you do not need to work around notarisation.

Install a prebuilt binary

Prebuilt binaries are available for a variety of systems and architectures. Refer to the release versions on GitHub for more details.

To install a prebuilt binary:

  1. Download the archive for the operating system and architecture you need.
  2. Extract the archive.
  3. Move the executable to the directory where you want to keep it.
  4. Make sure that directory is in your PATH.
  5. Make sure the file has execute permission.

If you use macOS, a manually downloaded binary might be blocked by Gatekeeper. For more information, refer to macOS Gatekeeper and killed: 9.

Install gcx from source

To install gcx with Go, you need:

To install, run:

shell 
go install github.com/grafana/gcx/cmd/gcx@latest

The version does not change after an upgrade

This page lists several install methods, and they write gcx to different directories. If you use two methods, you get two copies. Your shell runs the copy in the directory that comes first in PATH, and an upgrade of the other copy changes nothing that you can see.

List every copy:

sh 
which -a gcx

The first line is the copy that your shell runs. Remove the copies that you do not want:

PathInstall methodCommand that removes it
~/.local/bin/gcxInstall scriptrm ~/.local/bin/gcx
/usr/local/bin/gcxPrebuilt binary, or the script with GCX_INSTALL_DIRsudo rm /usr/local/bin/gcx
/opt/homebrew/bin/gcx, /home/linuxbrew/.../gcxHomebrewbrew uninstall gcx
~/go/bin/gcxgo installrm ~/go/bin/gcx

After you remove a copy, your shell can still hold the old path in its command hash table. Open a new terminal, or run:

sh 
hash -r

The install script reports this problem for you. It names both paths and both versions, and it gives the removal command.

macOS Gatekeeper and killed 9

macOS quarantines any downloaded binary by default. Since gcx release binaries are not yet Apple-notarised, macOS may block it the first time you run it. If this happens, you’ll see one of these two symptoms:

  • Intel macOS: A dialog says, “Apple could not verify ‘gcx’ is free of malware…”, and the binary doesn’t run.
  • Apple Silicon (M-series) macOS: The binary exits immediately with killed: 9 and no visible dialog.

Homebrew users are not affected. Homebrew does not set the xattr on the files that it installs.

Bypass the macOS gatekeeper

In manual downloads, bypass this by clearing the xattr and ad-hoc sign the binary so Apple Silicon accepts it:

sh 
xattr -d com.apple.quarantine "$(command -v gcx)" 2>/dev/null || true
codesign --sign - --force "$(command -v gcx)"   # required on Apple Silicon

Next, run gcx --version again; subsequent invocations should succeed without the block.

Note that these steps will no longer be necessary once gcx release binaries are Apple-notarised.