# Howto: Install Hugo on Mac

**URL:** <https://discourse.gohugo.io/t/howto-install-hugo-on-mac/768>\
**Category:** tips & tricks\
**Created:** [February 22, 2015, 10:25pm UTC](https://discourse.gohugo.io/t/howto-install-hugo-on-mac/768 "2015-02-22T22:25:03Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![michael\_henderson](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/michael_henderson/32/10490_2.png) [@michael\_henderson](https://discourse.gohugo.io/u/michael_henderson)\
**Post date:** [February 22, 2015, 10:25pm UTC](https://discourse.gohugo.io/t/howto-install-hugo-on-mac/768/1 "2015-02-22T22:25:03Z")

</div>

# Step 0: My Assumptions

1. You know how to open a terminal window.
2. You’re running a modern 64-bit Mac.
3. You will use `~/Sites` as the starting point for your site.

# Step 1: Decide between `brew`, downloading a tarball containing the binary, and compiling from source.

There are pros and cons for each.

1. `Brew` is the simplest and least work to maintain. The drawbacks aren’t severe. The package will be for the most recent release, so it will not have bug-fixes until the next release. The release to `brew` may lag a few days behind because it has to be coordinated with another team. Still, I’d recommend `brew` if you want to work from a stable, widely used source. It works well and is really easy to update.
2. Downloading the tarball and installing from it is also easy. You have to have a few more command line skills. Updates are easy, too. You just repeat the process with the new binary. This gives you the flexibility to have multiple versions on your computer. If you don’t want to use `brew`, then the binary is a good choice.
3. Compiling from source is the most work. The advantage is that you don’t have to wait for a release to add features or bug fixes. The disadvantage is that you need to spend more time managing the setup. It’s not a lot, but it’s more than with the other two options.

Since this is a “beginner” how-to, I’m going to cover the first two options in detail and gloss over the third. There are other documents on the Hugo web site that explain how to build from the sources.

# Brew

## Step 1: Install `brew` if you haven’t already

Go to the `brew` website, [http://brew.sh/](http://brew.sh/), and follow the directions there. The most important step is:

```auto
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

```

When I did this, I had some problems with directory permissions. Searches on Google pointed me to pages that walked me through updating permissions on the `/usr/local` directory. Seemed scary, but it’s worked well since.

## Step 2: Install `hugo`

```auto
$ brew install hugo
==> Downloading https://downloads.sf.net/project/machomebrew/Bottles/hugo-0.12.yosemite.bottle.1.tar.gz
######################################################################## 100.0%

```

Note that Hugo version 0.12 was the current release when I did this install. Also, there’s an issue with the build process. The version number of the package is correct, but when it builds it shows the version number of the release currently in work.

`Brew` should have updated your path to include Hugo. Confirm by running a few commands:

```auto
$ # show the location of the hugo executable
$ which hugo
/usr/local/bin/hugo

$ # show the installed version
$ ll $( which hugo )
lrwxr-xr-x 1 quoha admin 28 Feb 22 14:08 /usr/local/bin/hugo -> ../Cellar/hugo/0.12/bin/hugo

$ # verify that hugo runs correctly
$ hugo version
Hugo Static Site Generator v0.14-DEV BuildDate: 2015-02-22T14:08:09-06:00

```

You can see the issue with the version. `Brew` downloaded and installed 0.12, but the version is displayed as version 0.14. Until this is fixed, you have to check the link to find the actual version. In my case, the link is to `Cellar/hugo/0.12`, so I’m actually running version 0.12.

## Step 3: Update `hugo`

When it comes time to update Hugo, just run the brew upgrade command. That’s `upgrade`, not `update`. The `upgrade` command installs a newer version of a package while the `update` command installs a newer version of `brew`.

```auto
$ brew upgrade
==> Upgrading 1 outdated package, with result:
hugo 0.13
==> Upgrading hugo
==> Downloading https://homebrew.bintray.com/bottles/hugo-0.13.yosemite.bottle.tar.gz
######################################################################## 100.0%
==> Pouring hugo-0.13.yosemite.bottle.tar.gz
🍺 /usr/local/Cellar/hugo/0.13: 5 files, 27M

$ which hugo
/usr/local/bin/hugo

$ ll $( which hugo )
lrwxr-xr-x 1 quoha admin 28 Feb 22 14:35 /usr/local/bin/hugo -> ../Cellar/hugo/0.13/bin/hugo

$ hugo version
Hugo Static Site Generator v0.14-DEV BuildDate: 2015-02-22T02:09:28-06:00

```

Now you’re ready to create a new site.

# From Tarball

## Step 1: Decide on the location

When installing from the tarball, you have to decide if you’re going to install the binary in `/usr/local/bin` or in your home directory. There are three camps on this:

1. Install it in `/usr/local/bin` so that all the users on your system have access to it. This is a good idea because it’s a fairly standard place for exectuables. The downside is that you may need elevated privileges to put software into that location. Also, if there are multiple users on your system, they will all run the same version. Sometimes this can be an issue if you want to try out a new release.
2. Install it in `~/bin` so that only you can execute it. This is a good idea becase it’s easy to do, easy to maintain, and doesn’t require elevated privileges. The downside is that only you can run Hugo. If there are other users on your site, they have to maintain their own copies. That can lead to people running different versions. of course, this does make it easier for you to experiment with different releases.
3. Install it in your `sites` directory. This is not a bad idea if you have only one site that you’re building. It keeps every thing in a single place. If you want to try out new releases, you can just make a copy of the entire site, update the Hugo executable, and have it.

All three locations will work for you. I’m going to document the second option, mostly because I’m comfortable with it.

## Step 2: Download the Tarball

1. Open `https://github.com/spf13/hugo/releases` in your browser.
2. Find the current release by scrolling down and looking for the green tag that reads “Latest Release.”
3. Download the current tarball for the Mac. The name will be something like `hugo_X.YY_darwin_amd64.zip`, where `X.YY` is the release number.
4. By default, the tarball will be saved to your `~/Downloads` directory. If you chose to use a different location, you’ll need to change that in the following steps.

## Step 3: Confirm your download

Verify that the tarball wasn’t corrupted during the download:

```auto
$ tar tvf ~/Downloads/hugo_0.13_darwin_amd64.zip 
-rwxrwxrwx 0 0 0 0 Feb 22 04:02 hugo_0.13_darwin_amd64/hugo_0.13_darwin_amd64
-rwxrwxrwx 0 0 0 0 Feb 22 03:24 hugo_0.13_darwin_amd64/README.md
-rwxrwxrwx 0 0 0 0 Jan 30 18:48 hugo_0.13_darwin_amd64/LICENSE.md

```

The `.md` files are documentation. The other file is the executable.

## Step 3: Install into your bin directory

```auto
$ # create the directory if needed
$ mkdir -p ~/bin

$ # make it the working directory
$ cd ~/bin

$ # extract the tarball
$ tar zxf ~/Downloads/hugo_0.13_darwin_amd64.zip 
$ ll
total 24
drwxr-xr-x 6 quoha staff 204 Feb 22 14:58 .
drwxr-xr-x+ 40 quoha staff 1360 Feb 22 02:16 ..
lrwxr-xr-x 1 quoha staff 22 Sep 29 13:34 hugo -> hugo_0.12_darwin_amd/hugo_0.12_darwin_amd64
drwxr-xr-x 1 quoha staff 102 Sep 1 14:17 hugo_0.12_darwin_amd64
drwxr-xr-x 5 quoha staff 170 Feb 22 14:58 hugo_0.13_darwin_amd64
$ ll hugo_0.13_darwin_amd64/
total 27560
drwxr-xr-x 5 quoha staff 170 Feb 22 14:58 .
drwxr-xr-x 6 quoha staff 204 Feb 22 14:58 ..
-rwxr-xr-x@ 1 quoha staff 2707 Jan 30 18:48 LICENSE.md
-rwxr-xr-x@ 1 quoha staff 6748 Feb 22 03:24 README.md
-rwxr-xr-x@ 1 quoha staff 14095060 Feb 22 04:02 hugo_0.13_darwin_amd64

```

I was already running Hugo v0.12, so you can see how that was set up. It’ll be identical for v0.13 when we’re done.

```auto
$ # create the link to the real executable
$ rm -f hugo
$ ln -s hugo_0.13_darwin_amd64/hugo_0.13_darwin_amd64 hugo
$ ll
total 24
drwxr-xr-x 6 quoha staff 204 Feb 22 15:05 .
drwxr-xr-x+ 40 quoha staff 1360 Feb 22 02:16 ..
lrwxr-xr-x 1 quoha staff 45 Feb 22 15:04 hugo -> hugo_0.13_darwin_amd64/hugo_0.13_darwin_amd64
drwxr-xr-x 3 quoha staff 102 Feb 22 15:05 hugo_0.12_darwin_amd64
drwxr-xr-x 5 quoha staff 170 Feb 22 14:58 hugo_0.13_darwin_amd64

$ # verify that it runs
$ ./hugo version
Hugo Static Site Generator v0.13 BuildDate: 2015-02-22T04:02:30-06:00

```

You may need to add your bin directory to your `PATH` variable. The `which` command will check for us. If it can find `hugo`, it will print the full path to it. Otherwise, it will not print anything.

```auto
$ # check if hugo is in the path
$ which hugo
/Users/quoha/bin/hugo

```

If `hugo` is not in your `PATH`, add it by updating your `~/.bash_profile` file. First, start up an editor:

```auto
$ nano ~/.bash_profile

```

Add a line to update your `PATH` variable:

```auto
export PATH=$PATH:$HOME/bin

```

Then save the file by pressing Control-X, then Y to save the file and return to the prompt.

Close the terminal and then open a new terminal to pick up the changes to your profile. Verify by running the `which hugo` command again.

# Start a new site

Even though we just verified this, let’s check one more time that Hugo is installed correctly:

```auto
$ hugo help
A Fast and Flexible Static Site Generator built with
love by spf13 and friends in Go.

Complete documentation is available at http://gohugo.io

Usage: 
  hugo [flags]
  hugo [command]
  . . .
Use "hugo help [command]" for more information about a command.

```

Now that it’s working, set up a sample site.

```auto
$ cd ~/Sites
$ hugo new site sample
$ cd ~/Sites/sample
$ ll
total 8
drwxr-xr-x 8 quoha staff 272 Feb 22 15:55 .
drwxr-xr-x 6 quoha staff 204 Feb 22 15:55 ..
drwxr-xr-x 2 quoha staff 68 Feb 22 15:55 archetypes
-rw-r--r-- 1 quoha staff 83 Feb 22 15:55 config.toml
drwxr-xr-x 2 quoha staff 68 Feb 22 15:55 content
drwxr-xr-x 2 quoha staff 68 Feb 22 15:55 data
drwxr-xr-x 2 quoha staff 68 Feb 22 15:55 layouts
drwxr-xr-x 2 quoha staff 68 Feb 22 15:55 static

```

Grab a theme from the Hugo Themes repository. I’ll use the Hyde theme for this how-to. To get it, I opened [https://github.com/spf13/hyde](https://github.com/spf13/hyde) in my browser and clicked the “Download ZIP” button. That saved the file as `~/Downloads/hyde-master.zip`.

Add the theme to the sample site:

```auto
$ # add the theme to the config file
$ echo 'theme = "hyde-master"' >> config.toml

$ # install Hyde
$ mkdir -p themes
$ cd themes
$ unzip ~/Downloads/hyde-master.zip 
Archive: /Users/quoha/Downloads/hyde-master.zip
47f2ba81adf8702c33722350d0134dd96f08c1ed
   creating: hyde-master/
  inflating: hyde-master/LICENSE.md  
  inflating: hyde-master/README.md   
   creating: hyde-master/archetypes/
  inflating: hyde-master/archetypes/default.md  
   creating: hyde-master/images/
  inflating: hyde-master/images/screenshot.png  
  inflating: hyde-master/images/tn.png  
   creating: hyde-master/layouts/
   creating: hyde-master/layouts/_default/
  inflating: hyde-master/layouts/_default/list.html  
  inflating: hyde-master/layouts/_default/single.html  
  inflating: hyde-master/layouts/index.html  
   creating: hyde-master/layouts/partials/
  inflating: hyde-master/layouts/partials/head.html  
  inflating: hyde-master/layouts/partials/sidebar.html  
   creating: hyde-master/static/
   creating: hyde-master/static/css/
  inflating: hyde-master/static/css/hyde.css  
  inflating: hyde-master/static/css/poole.css  
  inflating: hyde-master/static/css/syntax.css  
  inflating: hyde-master/static/favicon.png  
  inflating: hyde-master/static/touch-icon-144-precomposed.png  
  inflating: hyde-master/theme.toml  
$ ll
total 0
drwxr-xr-x 3 quoha staff 102 Feb 22 16:00 .
drwxr-xr-x 8 quoha staff 272 Feb 22 15:55 ..
drwxr-xr-x@ 9 quoha staff 306 Oct 8 18:17 hyde-master
$ cd ..
$ ll
total 8
drwxr-xr-x 9 quoha staff 306 Feb 22 16:00 .
drwxr-xr-x 6 quoha staff 204 Feb 22 15:55 ..
drwxr-xr-x 2 quoha staff 68 Feb 22 15:55 archetypes
-rw-r--r-- 1 quoha staff 105 Feb 22 15:55 config.toml
drwxr-xr-x 2 quoha staff 68 Feb 22 15:55 content
drwxr-xr-x 2 quoha staff 68 Feb 22 15:55 data
drwxr-xr-x 2 quoha staff 68 Feb 22 16:01 layouts
drwxr-xr-x 2 quoha staff 68 Feb 22 15:55 static
drwxr-xr-x 3 quoha staff 102 Feb 22 16:01 themes

```

Create some sample content to test with:

```auto
$ cd ~/Sites/sample
$ hugo new post/one.md
/Users/quoha/Sites/sample/content/post/one.md created
$ hugo new post/two.md
/Users/quoha/Sites/sample/content/post/two.md created
$ ll content/post
total 16
drwxr-xr-x 4 quoha staff 136 Feb 22 16:07 .
drwxr-xr-x 3 quoha staff 102 Feb 22 16:07 ..
-rw-r--r-- 1 quoha staff 72 Feb 22 16:07 one.md
-rw-r--r-- 1 quoha staff 72 Feb 22 16:07 two.md

```

Open those two files up in your favorite editor and add some content after the second `+++` line. The file should look something like:

```auto
+++
date = "2015-02-22T16:07:06-06:00"
draft = true
title = "one"

+++

# heading

this is text

```

Of course you will have a different date.

Now you can test Hugo by generating the web site. One tricky thing is that “draft” flag in the posts. Since it is set to true, you must add a flag to the Hugo command line to tell it to build drafts. You’ll want to either remove the line or set it to false when you’re ready to publish your site for real.

```auto
$ hugo server --watch --buildDrafts --verbose
INFO: 2015/02/22 Using config file: /Users/quoha/Sites/sample/config.toml
INFO: 2015/02/22 syncing from /Users/quoha/Sites/sample/themes/hyde-master/static to /Users/quoha/Sites/sample/public/
INFO: 2015/02/22 syncing from /Users/quoha/Sites/sample/static/ to /Users/quoha/Sites/sample/public/
INFO: 2015/02/22 found taxonomies: map[string]string{"category":"categories", "tag":"tags"}
WARN: 2015/02/22 Unable to locate layout for 404 page: [404.html theme/404.html]
2 of 2 drafts rendered
0 future content 
2 pages created 
0 paginator pages created 
0 tags created
0 categories created
in 8 ms
Watching for changes in /Users/quoha/Sites/sample/content
Serving pages from /Users/quoha/Sites/sample/public
Web Server is available at http://localhost:1313/
Press Ctrl+C to stop

```

Now, open up your browser and point it to the `Web Server` URL listed in the output. (It is usually `http://localhost:1313`.)

Congratulations, you’re running a Hugo site. Now you’re ready to change this sample into your real site. Open your browser and start with the docs at [http://gohugo.io/overview/introduction/](http://gohugo.io/overview/introduction/).

---

<div class="post-metadata">

**Author:** ![spf13](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/spf13/32/37_2.png) [@spf13](https://discourse.gohugo.io/u/spf13)\
**Post date:** [February 22, 2015, 11:20pm UTC](https://discourse.gohugo.io/t/howto-install-hugo-on-mac/768/2 "2015-02-22T23:20:02Z")

</div>

This is great. Care to add it to the official docs?  
It would probably be good to have a page on windows, linux and Mac each.

Steve Francia[spf13.com](http://spf13.com)@spf13

---

<div class="post-metadata">

**Author:** ![michael\_henderson](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/michael_henderson/32/10490_2.png) [@michael\_henderson](https://discourse.gohugo.io/u/michael_henderson)\
**Post date:** [February 22, 2015, 11:21pm UTC](https://discourse.gohugo.io/t/howto-install-hugo-on-mac/768/3 "2015-02-22T23:21:29Z")

</div>

Let me give it a couple of days for the group to look over, then I’ll add it to the docs. And, maybe in the meantime that glitch with `brew` will be worked out.