Update, 2023-07-01: I later came up with a shell script that’s a lot simpler than the procedure explained herein (although, for Windows users, it works only on WSL).
When I indicated how I thought newcomers to the Hugo static site generator (SSG) should proceed — i.e., as opposed to the official path — I said this about the process of actually installing Hugo on one’s system:
Hugo is an app that you install on your computer. You can do that by either (a.) relying on a package manager app or (b.) directly downloading from the Hugo GitHub repository. Although I personally prefer the second method, most new users likely will find the first easier; so let’s go with package managers.
. . . and, in a footnote, I explained why I prefer the second method as opposed to using package managers:
The main thing I like about the direct-download method is that I can get a new Hugo version as soon as it’s available in the GitHub repo. With a package manager, you have to wait for the new version to be added to that app’s collection; although the accompanying delay often is only a few hours, it has occasionally stretched to multiple days.
That’s why, here, I’m going to explain how to employ that direct-download method.
(I base the following on my “Using Dart Sass with Hugo: the nitty-gritty,” which I note just in case you find any of it oddly familiar.)
Introduction
There are four tasks to perform, the first of which you should need to do only once:
- Create a
bin
folder in your user directory and add it to your systemPATH
. - Download/unpack the Hugo archive file, from which you’ll get the Hugo binary file.
- Move the Hugo binary to the
bin
folder. - Confirm that the system detects the Hugo binary as being in the
PATH
. (With macOS, this will include getting the binary “blessed,” as I’ll explain.)
With that established, let’s break this up into three sections that you can toggle to expand or compress so you’ll be looking at only what applies to you and your OS/device combo.
Linux
Click/tap here to toggle open/close.
Throughout these instructions, we will pretend that your user name is JohnDoe
. Thus, your user directory ({$HOME}
) will be /home/JohnDoe/
.
Update: Daniel F. Dickinson was kind enough to pass along these additional notes regarding Linux use, so please take them into account as you view the steps below.
• If $HOME
is mounted with the noexec
option, you must put the Hugo binary in a supported system location, and that will require root (or equivalent) access.
• The suggested procedure can also run into trouble if (a.) protection mechanisms like SELinux are in use, (b.) one is using an OSTree-based distribution, which may not allow the procedure, and/or (c.) one is within an enterprise-based Linux setup, which may have even more lockdown options and their associated complications.
Add a folder to your PATH
Create
/home/JohnDoe/bin/
if it doesn’t already exist. Thisbin
folder will be the target folder where you’ll store the Hugo binary.Determine which shell your setup is using,
bash
orzsh
:This will return eitherecho $0
bash
orzsh
.Use your preferred terminal-level text editor to open the appropriate file — either
/home/JohnDoe/.bashrc
or/home/JohnDoe/.zshrc
— and add the following:export PATH="$HOME/bin:$PATH"
Restart the terminal app, and check that
PATH
now includes your entry:echo $PATH
Get the archive file
Navigate to your default downloads destination,
/home/JohnDoe/Downloads/
.To get the latest version of Hugo, go to its GitHub releases page and download the corresponding
tar.gz
archive file for your particular system architecture, either 64-bit ARM (linux-arm64
) or 64-bit Intel/AMD (linux-amd64
).
Important: Always be sure to get the extended version, which usually will be found nearer to the bottom of the list of archives (you sometimes may have to click a link to show the entire list).To unpack the
.tar.gz
archive file to retrieve its contents, entertar -xf
followed by the name of the.tar.gz
file. (As an alternative, depending on your particular Linux distribution and windows manager, you may also be able to use a GUI to perform this operation.)
The resulting contents should be as shown in your downloads folder (here and below, for examples, we’re using Hugo 0.104.3 and the Linux version for 64-bit Intel/AMD CPUs):hugo_extended_0.104.3_Linux-64bit └─ hugo <-- the Hugo binary └─ LICENSE └─ README.md
Move the Hugo binary to bin
Note: If you’ve done this before and already have a Hugo binary within bin
, you do want to delete the existing one in favor of what you’ll be moving below.
Enter the following in your terminal app:
mv $HOME/Downloads/hugo_extended_0.104.3_Linux-64bit/hugo $HOME/bin
(As an alternative, depending on your particular Linux distribution and windows manager, you may also be able to use a GUI to perform this operation.)
Confirm the Hugo binary is in the PATH
Finally, to confirm that the Hugo binary is in the PATH
, enter the following in your terminal app:
hugo version
The result should look something like this:
hugo v0.104.3-58b824581360148f2d91f5cc83f69bd22c1aa331+extended linux/amd64 BuildDate=2022-10-04T14:25:23Z VendorInfo=gohugoio
If you get any other kind of response, it means the Hugo binary isn’t in the PATH
, after all, so you’ll have to go back through the procedure and figure out what you missed.
And that’s it. If you encounter errors in any of the above information, please let me know so I can fix it ASAP!
macOS
Click/tap here to toggle open/close.
Throughout these instructions, we will pretend that your user name is JohnDoe
. Thus, your user directory ({$HOME}
) will be /Users/JohnDoe/
.
Add a folder to your PATH
Create
/Users/JohnDoe/bin/
if it doesn’t already exist. Thisbin
folder will be the target folder where you’ll store the Hugo binary you’ll be getting shortly.Determine which shell your setup is using,
bash
orzsh
:This will return eitherecho $0
bash
orzsh
.Use your preferred terminal-level text editor to open the appropriate file — either
/Users/JohnDoe/.bashrc
or/Users/JohnDoe/.zshrc
— and add the following:export PATH="$HOME/bin:$PATH"
Restart the terminal app, and check that
PATH
now includes your entry:echo $PATH
Get the archive file
Navigate to your default downloads destination,
/Users/JohnDoe/Downloads/
.To get the latest version of Hugo, go to its GitHub releases page and download the
tar.gz
archive file for the macOS universal binary, which was available beginning with Hugo 0.102.0; for an earlier version, select either Apple Silicon (macos-arm64
) or Intel (macos-x64
).
Important: Always be sure to get the extended version, which usually will be found nearer to the bottom of the list of archives (you sometimes may have to click a link to show the entire list).To unpack the
.tar.gz
archive file to retrieve its contents, double-click the.tar.gz
file.
The resulting contents should be as shown inside your downloads folder (here and below, for examples, we’re using Hugo 0.104.3):hugo_extended_0.104.3_darwin-universal └─ hugo <-- the Hugo binary └─ LICENSE └─ README.md
Move the Hugo binary to bin
Use the macOS Finder to move the hugo
file to the bin
folder.
Note: If you’ve done this before and already have a Hugo binary within bin
, you do want to delete the existing one in favor of the latest version.
Get macOS to “bless” the Hugo binary
You’ll now have to get macOS to allow the use of the Hugo binary, which macOS considers to be from an unidentified developer (see “Open a Mac app from an unidentified developer” on the Apple Support site).
First, open the Mac System Preferences app and click the Security and Privacy settings icon. If necessary, click on its General tab. Then click its lock icon and enter your user password. This unlocks the “Allow apps downloaded from” area for a few minutes. Keep this open for now.
Next, in your terminal app, enter the following, which attempts to run the Hugo binary only to show its version:
hugo version
You’ll get a macOS warning about the file; click Cancel. Then, back in the Security and Privacy settings window, approve the use of the Hugo binary by clicking Allow Anyway. (If desired, you can now close the Mac System Preferences app.)
Note: If you get no such warning, it means the Hugo binary isn’t in the PATH
, after all, so you’ll have to go back through the procedure and figure out what you missed.
Go back to the terminal app and, once again, enter:
hugo version
This time, you’ll get a minor macOS warning but, this time, just click Open to bypass it — and this will tell macOS to stop such warnings in the future about this particular Hugo binary file. Now, in the terminal app, you’ll see something like this, which confirms not only the version info for the Hugo binary you installed but also that macOS has “blessed” it:
hugo v0.104.3-58b824581360148f2d91f5cc83f69bd22c1aa331+extended darwin/amd64 BuildDate=2022-10-04T14:25:23Z VendorInfo=gohugoio
And that’s it. If you encounter errors in any of the above information, please let me know so I can fix it ASAP!
Windows
Click/tap here to toggle open/close.
Throughout these instructions, we will pretend that your user name is JohnDoe
. Thus, your user directory will be C:\Users\JohnDoe\
.
Add a folder to your PATH
IMPORTANT: Because Windows truncates PATH
to 1,024 characters, first open Command Prompt and make a text backup of PATH
:
echo %PATH% > C:\path-backup.txt
If you need to restore the PATH
later, enter:
set %PATH%=>C:\path-backup.txt
- Create
C:\Users\JohnDoe\bin\
if it doesn’t already exist. Thisbin
folder will be the target folder where you’ll store the Hugo binary you’ll be getting shortly. - In the Windows Taskbar search box, search for
cmd
. - Select the Command Prompt result and click the Run as administrator option.
- In Command Prompt, enter:
setx PATH "C:\Users\JohnDoe\bin;%PATH%"
- Close Command Prompt.
- Repeat steps 2–3 to reload Command Prompt (with or without Run as administrator this time) and check the
PATH
to confirm your new entry is there:echo %PATH%
Get the archive file
Navigate to your default downloads destination,
C:\Users\JohnDoe\Downloads\
.To get the latest version of Hugo, go to its GitHub releases page and download the
.zip
archive file for Windows.
Important: Always be sure to get the extended version, which usually will be found nearer to the bottom of the list of archives (you sometimes may have to click a link to show the entire list); at this writing, there is no extended version for Windows ARM.In Windows Explorer, double-click the
.zip
file and choose to extract its contents, which should be as shown inside the regular downloads folder (here and below, for examples, we’re using Hugo 0.104.3):hugo_extended_0.104.3_windows-amd64 └─ hugo.exe <-- the Hugo binary └─ LICENSE └─ README.md
Move the Hugo binary to bin
Use Windows Explorer to move the hugo.exe
file to the bin
folder.
Note: If you’ve done this before and already have a Hugo binary within bin
, you do want to delete the existing one in favor of the latest version.
Confirm the Hugo binary is in the PATH
Finally, to confirm that the Hugo binary is in the PATH
, enter the following in Command Prompt:
hugo version
The result should look something like this:
hugo v0.104.3-58b824581360148f2d91f5cc83f69bd22c1aa331+extended windows/amd64 BuildDate=2022-10-04T14:25:23Z VendorInfo=gohugoio
If you get any other kind of response, it means the Hugo binary isn’t in the PATH
, after all, so you’ll have to go back through the procedure and figure out what you missed.
And that’s it. If you encounter errors in any of the above information, please let me know so I can fix it ASAP!
References
- Zachary Betz, “How to Add a Binary (or Executable, or Program) to Your PATH on macOS, Linux, or Windows” (2021-06-23).
- Talha Saif Malik, “How do I know if I have bash or zsh?” (2021-06-06).
- “Srini,” “Move files and directories to another location” (2014-01-05).
- Apple Support website, “Use zsh as the default shell on your Mac” (2020-01-28).
- JavaTpoint website, “Linux Home Directory” (retrieved 2022-05-22).
- ShellHacks website, “Windows CMD: PATH Variable — Add To PATH — Echo PATH” (2019-04-19).
- tar(1) Linux manual page (retrieved 2022-05-22).
- TheWindowsClub website, “How to Run Command Prompt as an Administrator in Windows 11/10” (2019-04-18).
Latest commit (ddfbbdb6
) for page file:
2023-09-22 at 10:57:57 AM CDT.
Page history