Managing Multiple Hugo Versions with hvm

This guide shows how to install and use hvm (Hugo Version Manager) to manage different Hugo versions across projects.

Installation

Method 1: Download Binary

1. Download the binary for your system:

# Replace OS_ARCH with your system:
# darwin-arm64, darwin-amd64, linux-amd64, linux-arm64, windows-amd64
OS_ARCH=darwin-arm64
VERSION=v0.8.2

curl -sL "https://github.com/jmooring/hvm/releases/download/${VERSION}/hvm-${OS_ARCH}.tar.gz" -o hvm.tar.gz
tar -xzf hvm.tar.gz
chmod +x hvm
sudo mv hvm /usr/local/bin/

Method 2: Install from Source

1. Ensure you have Go 1.24+ installed
2. Run the installation command:

VERSION=v0.8.2
go install github.com/jmooring/hvm@${VERSION}

Verify Installation

hvm help

Configuration

Set Up Shell Alias

Choose your shell and run the appropriate command:

# Zsh
hvm gen alias zsh >> ~/.zshrc

# Bash
hvm gen alias bash >> ~/.bashrc

# Fish
hvm gen alias fish >> ~/.config/fish/config.fish

# PowerShell
hvm gen alias powershell >> $PROFILE

Restart your terminal or source your configuration file.

Usage

Set Hugo Version for a Project

1. Navigate to your project directory
2. Run the version selector:

❯ hvm use

  1) v0.147.5              2) v0.147.4 [cached]     3) v0.147.3
  4) v0.147.2              5) v0.147.1              6) v0.147.0
  7) v0.146.7              8) v0.146.6              9) v0.146.5
 10) v0.146.4             11) v0.146.3             12) v0.146.2
 13) v0.146.1             14) v0.146.0             15) v0.145.0
 16) v0.144.2             17) v0.144.1             18) v0.144.0
 19) v0.143.1             20) v0.143.0             21) v0.142.0
 22) v0.141.0             23) v0.140.2             24) v0.140.1
 25) v0.140.0             26) v0.139.5             27) v0.139.4
 28) v0.139.3             29) v0.139.2             30) v0.139.1

Select a version to use in the current directory: v0.147.5
Please enter a number between 1 and 30, or press Enter to cancel: 1
Downloading v0.147.5... done.

3. Select your desired Hugo version from the list
4. hvm creates a .hvm file and installs the selected version

Configure Fallback Version

1. Install a default Hugo version:

hvm install

2. This version will be used in directories without a .hvm file

If you want the Hugo version to persist system wide, add the following to the PATH

Zsh - MacOS

echo 'export PATH="$HOME/Library/Caches/hvm/default:$PATH"' >> ~/.zshrc

Switch Between Projects

1. Each project with a .hvm file automatically uses its specified Hugo version
2. Projects without .hvm files use the fallback version
3. No manual switching required—hvm handles this automatically

File Structure

Your .hvm file contains a single line with the version:

v0.147.5

Place this file in your project root directory.

Verification

Check which Hugo version is active:

hugo version

This displays the version specified in your current directory’s .hvm file or the fallback version if no file exists.