How to migrate your Hugo blog environment from Windows to macOS

I recently switched my daily driver from a Windows PC to a MacBook. So I had to perform a migration and reconfiguration of my personal Hugo blog’s development environment. Here’s a step-by-step guide of the process I followed.

Migrate Your Codebase

#

Before you start, make sure all local changes from your old Windows PC have been committed and pushed to GitHub. This ensures the cloud version of your repository is fully in sync and ready for the migration.

Once your cloud repository is fully in sync, it’s time to clone it onto your new Mac.

Note: If your theme (like themes/blowfish in my case) is managed as a Git Submodule, I strongly recommend using the --recurse-submodules flag when cloning. This downloads the theme and all its files in one go.

git clone --recurse-submodules <your_repo_URL> your_project_folder

If you’re using the GitHub Desktop client, this is even simpler: just go to File > Clone Repository..., select your repo and local path, and it will handle the submodules for you.

If you only cloned the main project, don’t worry. You can run the following command to manually pull in the submodules:

cd ~/your_project
git submodule update --init --recursive

Clean Up the Environment & .gitignore

#

It’s crucial to clean out any platform-specific or auto-generated folders from Windows. These files should never be tracked by Git.

node_modules/: Node.js dependencies. You must delete this, as it often contains binaries compiled for Windows and will be useless (or cause errors) on macOS.

public/: The generated Hugo site.

resources/: Hugo’s cache folder.

To make sure Git ignores these folders permanently, we need to configure .gitignore file. Run nano .gitignore in your project root and make sure it contained at least the following:

# Hugo generated folders
/public
/resources

# Node.js dependencies
/node_modules

# macOS specific files
.DS_Store

Save the file and exit nano (Press Control + O, Enter, then Control + X).

Install Node.js

#

A fresh macOS setup doesn’t come with Node.js by default. The easiest way to install it is using Homebrew.

brew install node

Install and Configure Hugo

#

For installing Hugo, you have a couple of options on macOS.

Option 1: Homebrew (Easy, can auto-updates)

#

This is the simplest method. Homebrew will grab and install the latest stable “extended” version of Hugo for you.

brew update       # Fetch the latest package lists
brew upgrade      # Optional: upgrade all your existing packages
brew install hugo
hugo version      # Verify the installation

Option 2: Manual Install (To lock your version)

#

If you want to use a specific Hugo version and prevent auto-updating by Homebrew (which can sometimes break a site), you can install Hugo manually.

• Download: Go to the Hugo GitHub Releases page. Find the specific version you need and download the correct package. For an Apple Silicon Mac, this is usually hugo_extended_..._darwin-universal.tar.gz.

• Unzip & Place: Unzip the file and place the hugo binary file in a stable location. For this example, I put mine in $HOME/Documents/project/about/hugo.

• Configure Path: You need to edit the .zshrc configuration file as macOS default. From your home directory, run nano ~/.zshrc. Add the following line to the file. This places your custom Hugo path at the front of the $PATH variable, ensuring the system uses your manually-installed version first. (While other versions of Hugo might exist on your system, tools installed via Homebrew are usually found in /opt/homebrew/bin)

#Point to my manually installed Hugo binary
export PATH="$HOME/Documents/project/about/hugo:$PATH"

Save and exit (Control + O, Enter, Control + X), then run source ~/.zshrc to apply the changes to your current terminal session.

(Optional) Update Theme Version

#

Since I was already doing a clean setup, I took the opportunity to update my theme. If you just want the latest version of your theme (assuming it’s a submodule):

cd themes/blowfish       # Enter the theme directory
git pull origin main     # Pull the latest updates
cd ../..                 # Go back to the project root
git add themes/blowfish  # Stage the submodule change
git commit -m "Update blowfish theme"

If you prefer to pin your theme to a specific stable release (which I highly recommend):

cd themes/blowfish       # Enter the theme directory
git tag                  # (Optional) See all available version tags
git checkout v2.90.0     # Checkout a specific version tag
cd ../..                 # Go back to the project root
git add themes/blowfish  # Stage the submodule change
git commit -m "Pin Blowfish theme to stable release v2.90.0"

Final Step: Install Dependencies

#

After cloning and setting up your tools, run npm install to install the Node.js dependencies for your project. This reads your package.json file and pulls all the necessary libraries that your theme and Hugo rely on.

Also, after switching theme versions, re-run npm install to ensure your Node.js dependencies align with the current theme version.

Now, you are able to run hugo server, and the blog should be back online. Mission complete!

Cover image: This artist’s concept depicts the protoplanet WISPIT 2b accreting matter as it orbits around its star, WISPIT 2. From NASA