Skip to content

Latest commit

 

History

History
475 lines (317 loc) · 17.5 KB

install_and_upgrade.md

File metadata and controls

475 lines (317 loc) · 17.5 KB

Install/upgrade

For common Unix-like operating systems, including macOS, all you need to do is run:

curl -sSL https://get.haskellstack.org/ | sh

or:

wget -qO- https://get.haskellstack.org/ | sh

This script will ask for root access using sudo. It needs this access in order to use your platform's package manager to install dependencies and to install to /usr/local/bin. If you prefer more control, follow the manual installation instructions for your platform below.

Binaries for other operating systems are listed below, and available on the GitHub release page. For the future, we are open to supporting more operating systems (to request one, please submit an issue).

Binary packages are signed with this signing key.

If you are writing a script that needs to download the latest binary, you can use URLs like https://get.haskellstack.org/stable/<PLATFORM>.<EXTENSION> (e.g. https://get.haskellstack.org/stable/linux-x86_64.tar.gz) that always point to the latest stable release.

Windows

We recommend installing to the default location with these installers, as that will make stack install and stack upgrade work correctly out of the box.

You may see a "Windows Defender SmartScreen prevented an unrecognized app from starting" warning when you try to run the installer. If so, click on More info, and then click on the Run anyway button that appears.

Manual download

  • Download the latest release:

  • Unpack the archive and place stack.exe somewhere on your PATH (see the Path section below).

  • Now you can run Stack from the command line in a terminal.

macOS

We generally test on the current version of macOS and do our best to keep it compatible with the three most recent major versions. Stack may also work on older versions.

Installer script

Run:

curl -sSL https://get.haskellstack.org/ | sh

Manual download

  • Download the latest release:

  • Extract the archive and place stack somewhere on your PATH (see the Path section below).

  • Now you can run Stack from the command line in a terminal.

Using Homebrew

Homebrew is a popular package manager for macOS. If you have its brew tool installed, you can just do:

brew install haskell-stack

  • The Homebrew formula and bottles are unofficial and lag slightly behind new Stack releases, but tend to be updated within a day or two.

  • Normally, Homebrew will install from a pre-built binary (aka "pour from a bottle"), but if it starts trying to build everything from source (which will take hours), see their FAQ on the topic.

Notes

After installation, running stack setup might fail with configure: error: cannot run C compiled programs. in which case you should run:

xcode-select --install

Starting with macOs 10.14 (Mojave) running xcode-select --install might not be enough. You will need to install additional headers by running:

cd /Library/Developer/CommandLineTools/Packages/
open macOS_SDK_headers_for_macOS_10.14.pkg

If you are on OS X 10.11 (El Capitan) and encounter either of these problems, see the linked FAQ entries:

If you are on macOS 10.12 (Sierra) and encounter GHC panic while building, see this issue

On Apple silicon chip (AArch64/ARM64) architectures, the installation of Stack or some packages (e.g. network) requiring C source compilation might fail with configure: error: C compiler cannot build executables. In that case you should pass -arch arm64 as part of the CFLAGS environment variable. This setting will be picked up by the C compiler of your choice.

# Assuming BASH below

# passing CFLAGS in-line with the command giving rise to the error
CFLAGS="-arch arm64 ${CFLAGS:-}" some_command_to_install_stack
CFLAGS="-arch arm64 ${CFLAGS:-}" stack [build|install]

# -- OR --

# ~/.bash_profile
# NOTE: only do this if you do not have to cross-compile, or remember to unset
# CFLAGS when needed
export CFLAGS="-arch arm64 ${CFLAGS:-}"

The setting instructs the C compiler to compile objects for ARM64. These can then be linked with libraries built for ARM64. Without the instruction, the C compiler, invoked by Cabal running in x86-64, would compile x86-64 objects and attempt to link them with existing ARM64 libraries, resulting in the error above.

Ubuntu

Use the generic Linux option.

There is also a Ubuntu package for Ubuntu 16.10 and up, but the distribution's Stack version lags behind, so we recommend running stack upgrade --binary-only after installing it. For older Stack versions which do not support --binary-only, just stack upgrade may work too. The version in Ubuntu 16.04 is too old to upgrade successfully, and so in that case Stack should be installed from a release tarball.

Debian

Use the generic Linux option.

There is also a Debian package for Stretch and up, but the distribution's Stack version lags behind, so running stack upgrade --binary-only is recommended after installing it. For older Stack versions which do not support --binary-only, just stack upgrade may work too.

CentOS / Red Hat / Amazon Linux

Use the generic Linux option.

There is also an unofficial Copr repo. This Stack version may lag behind, so we recommend running stack upgrade after installing it.

Fedora

Use the generic Linux option.

Fedora includes builds of Stack, but the version may lag behind, so we recommend running stack upgrade after installing it.

openSUSE / SUSE Linux Enterprise

Use the generic Linux option.

There is also an unofficial SUSE package. This Stack version may lag behind, so we recommend running stack upgrade after installing it. To install it:

  1. Add the appropriate OBS repository:

    • openSUSE Tumbleweed

      all needed is in distribution

    • openSUSE Leap

      sudo zypper ar http://download.opensuse.org/repositories/devel:/languages:/haskell/openSUSE_Leap_42.1/devel:languages:haskell.repo

    • SUSE Linux Enterprise 12

      sudo zypper ar http://download.opensuse.org/repositories/devel:/languages:/haskell/SLE_12/devel:languages:haskell.repo

  2. Install:

     sudo zypper in stack

Arch Linux

There is an official package in the Arch community repository. So you can install it by simply doing:

sudo pacman -S stack

This version may slightly lag behind, but it should be updated within the day. The package is also always rebuilt and updated when one of its dependencies gets an update.

In order to use stack setup with older versions of GHC or on a 32-bit system, you may need the ncurses5-compat-libs AUR package installed. If this package is not installed, Stack may not be able to install older (< 7.10.3) or 32-bit GHC versions.

If you use the ArchHaskell repository, you can also get the haskell-stack-tool package from there.

NixOS

Users who follow the nixos-unstable channel or the Nixpkgs master branch can install the latest Stack release into their profile by running:

nix-env -f "<nixpkgs>" -iA stack

Alternatively, the package can be built from source as follows.

  1. Clone the git repo:

     git clone https://github.com/commercialhaskell/stack.git

  2. Create a shell.nix file:

     cabal2nix --shell ./. --no-check --no-haddock > shell.nix

    Note that the tests fail on NixOS, so disable them with --no-check. Also, Haddock currently doesn't work for Stack, so --no-haddock disables it.

  3. Install Stack to your user profile:

     nix-env -i -f shell.nix

For more information on using Stack together with Nix, please see the NixOS manual section on Stack.

Linux (generic)

Installer script

Run:

curl -sSL https://get.haskellstack.org/ | sh

or:

wget -qO- https://get.haskellstack.org/ | sh

Manual download

  • Download the latest release:

  • Extract the archive and place stack somewhere on your PATH (see the Path section below)

  • Ensure you have required system dependencies installed. These include GCC, GNU Make, xz, perl, libgmp, libffi, and zlib. We also recommend Git and GPG. To install these using your package manager:

    • Debian / Ubuntu: sudo apt-get install g++ gcc libc6-dev libffi-dev libgmp-dev make xz-utils zlib1g-dev git gnupg netbase

    • Fedora / CentOS: sudo dnf install perl make automake gcc gmp-devel libffi zlib zlib-devel xz tar git gnupg (use yum instead of dnf on CentOS and Fedora <= 21)

      • Fedora 24: In order to use stack setup on a 32-bit system, you may need to run sudo dnf install ncurses-compat-libs. If this package is not installed, Stack may not be able to install 32-bit GHC versions.

    • Arch Linux: sudo pacman -S make gcc ncurses git gnupg xz zlib gmp libffi zlib

      • In order to use stack setup with older versions of GHC or on a 32-bit system, you may need the ncurses5-compat-libs AUR package installed. If this package is not installed, Stack may not be able to install older (< 7.10.3) or 32-bit GHC versions.

    • Gentoo users, make sure to have the ncurses package with USE=tinfo (without it, Stack will not be able to install GHC).

  • Now you can run Stack from the command line in a terminal.

Path

You can install Stack by copying the executable file anywhere on your PATH. A good place to install is the same directory where Stack itself will install executables. On Windows, that directory is %APPDATA%\local\bin, e.g. c:\Users\<user-name>\AppData\Roaming\local\bin. For other systems, it's $HOME/.local/bin.

If you don't have that directory in your PATH, you may need to update your PATH (such as, on Unix-like operating systems, by editing ~/.bashrc).

If you're curious about the choice of these directories, see issue #153

Shell auto-completion

To get tab-completion of commands on bash, just run the following (or add it to .bashrc):

eval "$(stack --bash-completion-script stack)"

For more information and other shells, see the shell auto-completion page.

China-based users

If you're attempting to install Stack from within China:

  • As of 24 February 2020, the download link has limited connectivity from within mainland China. If this is the case, please proceed by manually downloading (ideally via a VPN) and installing Stack per the instructions found on this page pertinent to your operating system.

  • After installation, your config.yaml file will need to be configured before Stack can download large files consistently from within China (without reliance on a VPN). Please add the following to the bottom of the config.yaml file:

###ADD THIS IF YOU LIVE IN CHINA
setup-info-locations:
- "http://mirrors.tuna.tsinghua.edu.cn/stackage/stack-setup.yaml"
urls:
  latest-snapshot: http://mirrors.tuna.tsinghua.edu.cn/stackage/snapshots.json

package-indices:
  - download-prefix: http://mirrors.tuna.tsinghua.edu.cn/hackage/
    hackage-security:
        keyids:
        - 0a5c7ea47cd1b15f01f5f51a33adda7e655bc0f0b0615baa8e271f4c3351e21d
        - 1ea9ba32c526d1cc91ab5e5bd364ec5e9e8cb67179a471872f6e26f0ae773d42
        - 280b10153a522681163658cb49f632cde3f38d768b736ddbc901d99a1a772833
        - 2a96b1889dc221c17296fcc2bb34b908ca9734376f0f361660200935916ef201
        - 2c6c3627bd6c982990239487f1abd02e08a02e6cf16edb105a8012d444d870c3
        - 51f0161b906011b52c6613376b1ae937670da69322113a246a09f807c62f6921
        - 772e9f4c7db33d251d5c6e357199c819e569d130857dc225549b40845ff0890d
        - aa315286e6ad281ad61182235533c41e806e5a787e0b6d1e7eef3f09d137d2e9
        - fe331502606802feac15e514d9b9ea83fee8b6ffef71335479a2e68d84adc6b0
        key-threshold: 3
        ignore-expiry: no

Using an HTTP proxy

To use Stack behind a HTTP proxy with IP address IP and port PORT, first set up an environment variable http_proxy and then run the Stack command. For example:

$ export http_proxy=IP:PORT
$ stack install

On most operating systems, it is not mandatory for programs to follow the "system-wide" HTTP proxy. Some programs, such as browsers, do honor this "system-wide" HTTP proxy setting, while other programs, including bash, do not. That means configuring "http proxy setting" in your Control Panel (Windows) or System Preferences (Mac) would not result in Stack traffic going through the proxy.

Upgrade

There are essentially four different approaches to upgrade:

  • Stack itself ships with an upgrade command, which downloads a stack binary or builds it from source and install it to the default install directory (eg stack path --local-bin; see the Path section above). You can use stack upgrade to get the latest official release, and stack upgrade --git to install from Git and live on the bleeding edge. Make sure the default install directory is on your PATH and takes precedence over the system installed stack, or copy stack from that directory to the system location afterward. For more information, see this discussion.

  • If you're using a package manager and are happy with sticking with the officially released binaries from the distribution (which may the lag behind latest version of Stack significantly), simply follow your normal package manager strategies for upgrading (eg apt-get update && apt-get upgrade).

  • The get.haskellstack.org script supports the -f argument to over-write the current Stack executable. For example:

    curl -sSL https://get.haskellstack.org/ | sh -s - -f

    or:

    wget -qO- https://get.haskellstack.org/ | sh -s - -f

  • Manually follow the steps above to download the newest binaries from the release page and replace the old binary.

Install earlier versions

To install a specific version of Stack, navigate to the desired version on the GitHub release page, and click the appropriate link under its "Assets" drop-down menu.

Alternatively, use the URL https://github.com/commercialhaskell/stack/releases/download/vVERSION/stack-VERSION-PLATFORM.EXTENSION. For example, the tarball for Stack version 2.1.0.1, osx-x86_64 is at https://github.com/commercialhaskell/stack/releases/download/v2.1.0.1/stack-2.1.0.1-osx-x86_64.tar.gz.

Here's a snippet for appveyor.yml files, borrowed from dhall's appveyor.yml. Change the values of PATH and VERSION as needed.

install:
  - set PATH=C:\Program Files\Git\mingw64\bin;%PATH%
  - curl --silent --show-error --output stack.zip --location "https://github.com/commercialhaskell/stack/releases/download/v%STACK_VERSION%/stack-%STACK_VERSION%-windows-x86_64.zip"
  - 7z x stack.zip stack.exe
  - stack setup > nul
  - git submodule update --init --recursive