ghcup

Start the interactive TUI

$ ghcup tui

$ ghcup list

$ ghcup install ghc

$ ghcup install ghc [version]

$ ghcup set ghc [version]

$ ghcup install cabal

$ ghcup upgrade

ghcup [OPTIONS] COMMAND [ARGS...]

install [version]
    Installs a specific version of a tool (e.g., ghc, cabal, stack, ghcjs). If no version is specified, the recommended version is installed.

set
    Sets a specific installed version of a tool as the default for the current user.

list
    Lists all available and currently installed versions of various Haskell tools.

upgrade
    Upgrades ghcup itself to the latest version or updates installed Haskell tools to their recommended versions.

rm [version]
    Removes one or more installed versions of a specified tool. If no version is given, it removes all installed versions of that tool.

cabal
    Executes the ghcup-managed Cabal build tool with the provided arguments.

stack
    Executes the ghcup-managed Stack build tool with the provided arguments.

tui
    Launches an interactive Text User Interface (TUI) for easier visual management of tools and versions.

path
    Displays information about how ghcup manages the system's PATH environment variable for its tools.

whereis
    Shows the full filesystem path to the currently active ghcup-managed executable for a given tool.

run [args...]
    Runs a specific, explicitly chosen version of a tool, overriding the default set version.

config
    Allows managing various configuration settings for ghcup itself, such as mirror URLs or download behavior.

help [command]
    Displays general help information or detailed help for a specific ghcup command.

version
    Displays the current version number of the ghcup client.

ghcup is a robust command-line tool designed to simplify the installation and management of the Haskell toolchain. This includes the Glasgow Haskell Compiler (GHC), the Cabal build tool, the Stack build tool, and GHCJS. It provides a unified interface for users to easily install specific versions, switch between them, upgrade existing components, and remove unwanted installations.

The primary goal of ghcup is to offer a consistent, cross-platform, and hassle-free experience for setting up and maintaining a Haskell development environment, handling dependencies and ensuring compatibility across different projects. It has become the recommended method for new and experienced Haskell developers to get started.

Initial setup and installations require active internet connectivity to download tool binaries.
ghcup modifies shell configuration files (e.g., ~/.bashrc, ~/.zshrc) to ensure its managed tools are correctly added to the system's PATH. Users should be aware of these changes.
Successful installation of certain tools may depend on the presence of system-level build dependencies (e.g., GCC, make, curl, xz) which ghcup does not automatically install.
Primarily focuses on binary distributions. Building tools from source via ghcup is not its main use case.

During its initial setup, ghcup typically prompts to modify your shell's configuration file (like ~/.bashrc or ~/.zshrc) to prepend its binary directory to your PATH environment variable. This ensures that the ghcup-managed versions of tools are found before any system-installed ones. After modification, you often need to source your shell configuration (e.g., source ~/.bashrc) or restart your terminal for changes to take effect.

For scripting or automated environments, ghcup supports non-interactive installation. Options like --no-modify-path, --no-install-ghc, --skip-update, and --verbose can be used to control its behavior without user prompts. This is useful for CI/CD pipelines or reproducible development setups.

ghcup emerged as a modern solution to the fragmented and often complex landscape of Haskell toolchain installation. Prior to its development, setting up a Haskell environment often involved manual installations, relying on potentially outdated system package managers, or using less comprehensive platform-specific installers. ghcup was designed to unify this experience, providing a consistent, cross-platform, and robust way to manage GHC, Cabal, and Stack. Its development has been community-driven, aiming to streamline the developer onboarding process and provide a reliable foundation for Haskell project management.

cabal(1), stack(1), ghc(1), nvm(1) (Node Version Manager - conceptually similar), pyenv(1) (Python Version Manager - conceptually similar)