FP Haskell Center

The easiest way to get started with Yesod is by using FP Haskell Center. FP Haskell Center provides a web based development environment with all of the Haskell toolchain and Yesod libraries preinstalled. You can get started right away by cloning an existing Yesod project.

The rest of this page provides instructions for installing on your local system.

Stackage Server

The recommended approach for installing Yesod on your local system is to use Stackage Server. Stackage Server ensures you will get a set of packages that are known to compile together and run correctly, instead of needing to find a working package set yourself. This avoids the oft-sited "cabal hell" users have faced in the past.

  1. Make sure your system is prepared to use Stackage Server.
  2. Choose a Stackage snapshot and configure your system to use it. See the Getting Started section on the Stackage Server homepage.
  3. Install prerequisite build tools: cabal install alex happy
  4. Install the yesod binary
  5. Run yesod init and answer its questions to create a new scaffolded application
  6. cd into the newly created directory
  7. Install all library dependencies with cabal install --enable-tests --reorder-goals --max-backjumps=-1 -j
    • Note: This can take a while. On a fast computer, it will take around 10 minutes. On a slower system, it can take up to 40.
  8. Start up the devel server with yesod devel.
  9. View your new site at http://localhost:3000/.

Learn more

Now it's time to start coding! You can play around with the code right now, or if you want to learn more, check out these resources:

Without Stackage Server

You are not required to use Stackage Server to install Yesod. If you would instead like to use regular Hackage, simply install your GHC and cabal-install as normal, and do not configure cabal to use a Stackage snapshot. Note that you will be more likely to run into dependency conflicts if you go this route.

Legacy instructions

These instructions are prior to August 2014, when we switched to recommending Stackage Server. They are kept in case anyone needs to recreate an old build, or has issues using Stackage Server.

Getting Haskell

You'll need two main tools: the Glasgow Haskell Compiler (GHC) and cabal-install, the package installer. The best way to get them is with the Haskell Platform.

If you're on Windows or Mac, download the installers from the Haskell Platform site. For Linux users, most distributions already include the platform in the repositories. On most Debian-based systems, for example, you can just run

sudo apt-get install haskell-platform

Make sure to add $HOME/.cabal/bin to your PATH. Once you're set up, run

cabal update

to download a list of available packages. For more information on Haskell tools, see the tools chapter of the Mezzo Haskell book. Mac users may also want to see this page for help with their PATH setting.

Note: Mac users on Mavericks should be sure to read about the clang wrapper script to get CPP working correctly. It's highly recommended for now to use GCC's CPP implementation.

Install Yesod

Building Yesod and all of its dependencies is a simple procedure. Just run:

cabal update
cabal install yesod-platform yesod-bin --max-backjumps=-1 --reorder-goals

Note that this will be installing a large number of packages, and may take a while. (15 minutes on modern systems, up to 40 minutes on older systems.) This is a one time setup, and will have no impact on normal development or runtime performance.

Start a new site

Now I'm sure you want to test this out! The yesod executable has two important commands.

yesod init

will ask you a few questions, and then generate a scaffolded site for you. At this point, you can follow the onscreen instructions to build and run your site. At the time of writing this page, the instructions are:

cabal sandbox init
cabal install --enable-tests . yesod-platform yesod-bin --max-backjumps=-1 --reorder-goals
yesod devel

which will set up a sandboxed environment, install all dependencies, and start the development server. After this is completed, you can access your site at http://localhost:3000/.

(Note: If the command line tool gives you different instructions, you should follow those instead.)