Written by Andrew
on January 9, 2025

How to setup Hugo on MacOS using Podman

Hugo is a popular static website builder that works on Windows, Linux and MacOS.

If you’re a Mac user, you can install it easily by downloading the pre-built binary or install it using a package manager such as Homebrew or MacPort. But if you’d rather not install locally and don’t want to use a server, you can use Podman to run hugo in a container on your machine.

This articles goes through the process of setting up Podman and get Hugo running from the command line.

Podman

Download and install Podman Desktop from podman.io

Once installed launch the Podman Desktop.

On MacOS and Windows you need to create a VM to run containers.

Podman desktop will walk you through the setup on first run.

Create a blank Hugo website

To create a new blank hugo site in your documents folder, run the following in your terminal:

cd ~/Documents
podman run --rm -it -v $(pwd):/src:z hugomods/hugo:exts-non-root hugo new site quickstart

You’ll now have a new blank site called quickstart created in your documents folder, and you’ll be prompted with instructions for setting up a theme:

Congratulations! Your new Hugo site was created in /src/quickstart.

Just a few more steps...

1. Change the current directory to /src/quickstart.
2. Create or install a theme:
- Create a new theme with the command "hugo new theme <THEMENAME>"
- Or, install a theme from https://themes.gohugo.io/
3. Edit hugo.toml, setting the "theme" property to the theme name.
4. Create new content with the command "hugo new content <SECTIONNAME>/<FILENAME>.<FORMAT>".
5. Start the embedded web server with the command "hugo server --buildDrafts".

Add a theme to the site

Move into the quickstart folder and add a new theme as a git submodule:

cd ~/Documents/quickstart
git init
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke

Append a line to the site configuration file, to indicate the current theme:

echo "theme = 'ananke'" >> hugo.toml

Serve the hugo site on localhost

Create a cache folder for the local build:

mkdir hugo_cache

and to run the development server using podman:

podman run --rm \                                                                       
  --name mysite \
  -p 1313:1313 \
  -v ${PWD}:/src \
  -v ${PWD}/hugo_cache:/tmp/hugo_cache \
  hugomods/hugo:exts-non-root \
  server -p 1313

Open your browser at http://localhost:1313 and you’ll see a Hugo site being served, albeit without any content.

The command is quite long, so I recommend making a little bash script.

Add a sample page

Your posts are saved in the content/posts folder.

You can use hugo to create the markdown file for you, which will include frontmatter, or add a file manually.

To use hugo:

podman run --rm -it -v $(pwd):/src:z hugomods/hugo:exts-non-root hugo new content content/posts/my-first-post.md

Open the markdown file in your editor and add your content.

By default all new posts are marked as draft, so if you want to see it locally, add -D when building the site:

podman run --rm \                                                                       
  --name mysite \
  -p 1313:1313 \
  -v ${PWD}:/src \
  -v ${PWD}/hugo_cache:/tmp/hugo_cache \
  hugomods/hugo:exts-non-root \
  server -D -p 1313

You’ve now got a site up and running locally using Podman and Hugo.

Add more content to your content/posts directory.

← Top