Important note, 2023-06-20: There has been a breaking change in how Embedded Dart Sass is packaged, and Hugo 0.114.0 is the first version that supports the new packaging, which uses the Dart Sass package. I have revised this post’s instructions for Hugo 0.114.0 and newer. If forced to use an older version of Hugo, you must continue with the older, archived Embedded Dart Sass packaging and the former versions of the instructions, which you can find in this page’s history.
Also: while these instructions are about installing a prebuilt Sass binary, please note that you may find it considerably more convenient to use a package manager, instead, as explained in this comprehensive post by Joe Mooring on the Hugo Discourse forum. (I personally prefer installing a prebuilt binary, mainly because I’d rather not wait for a package manager to update its repository whenever there’s a new release of the binary — but, if that doesn’t concern you, you’ll likely prefer using a package manager.)
Some of the responses I got to my recent post, “Using Dart Sass with Hugo: the GitHub Actions edition,” made it clear that there needs to be a one-stop guide that tells how to set up the Dart Sass binary in the PATH
on one’s local machine for use with the Hugo static site generator (SSG).
So let’s take care of that right now, shall we?
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 (and a designated subfolder-to-come) to your systemPATH
. - Download/unpack the Dart Sass archive file.
- Move the resulting
dart-sass
folder — the aforementioned “subfolder-to-come” — to thebin
folder. - Confirm that the system detects the
dart-sass
folder as being in thePATH
.
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.
Note from the future: The reason we’ll be adding both bin
and bin/dart-sass
to the PATH
is so that, if you also like to download and install the Hugo binary rather than depending on a package manager (e.g., as explained in my later post, “How I install Hugo”), you can use bin
for that purpose. It seems to me that the two installations — the Hugo binary and the Dart Sass binary — are sufficiently akin as to suggest such a method.
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/
.
Add a folder and subfolder 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 contents of the Dart Sass archive file 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
/home/JohnDoe/.bashrc
or/home/JohnDoe/.zshrc
— and add the following lines:export PATH="$HOME/bin:$PATH" export PATH="$HOME/bin/dart-sass:$PATH"
Restart the terminal app, and check that
PATH
now includes your entries:echo $PATH
Get the archive file
Navigate to your default downloads destination,
/home/JohnDoe/Downloads/
.To get the latest version of Dart Sass, go to its GitHub releases page and download the corresponding
tar.gz
archive file for your particular system architecture:- 64-bit ARM (
linux-arm64
) - 32-bit ARM (
linux-arm
) - x64 (
linux-x64
) - IA-32 (
linux-ia32
)
- 64-bit ARM (
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.) This will result in asass_embedded
folder, the contents of which will depend on whichtar.gz
archive file you chose.
Move the dart-sass
folder to bin
Note: If you’ve done this before and already have a dart-sass
folder 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/dart-sass $HOME/bin/dart-sass
Confirm dart-sass
is in the PATH
Finally, to confirm that the dart-sass
folder and its contents are in the PATH
, enter the following in your terminal app:
sass --embedded --version
This will run the sass
shell script included in the dart-sass
folder. The result should look something like this example from Dart Sass v.1.63.4:
{
"protocolVersion": "2.1.0",
"compilerVersion": "1.63.4",
"implementationVersion": "1.63.4",
"implementationName": "Dart Sass",
"id": 0
}
If you get any other kind of response, it means the dart-sass
folder isn’t in the PATH
, after all, so you’ll have to go back through the procedure and figure out what you missed.
Note: If you get a response that shows a wrong version number in compilerVersion
and/or implementationVersion
, you apparently haven’t moved over the entire dart-sass
folder that you got from unpacking the .tar.gz
archive file.
And that’s it. I hope this has spared you some searching. If you encounter errors in any of the above information, please let me know so I can fix it ASAP!
Reminder: In a worst-case scenario in which you can’t get this to work no matter what you do, there’s always the option of using the Node.js Sass package, instead, as I described in the original article in this series. It’s not quite as elegant for Hugo’s purposes, and it definitely is slower than using the Dart Sass binary, but it works.
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 and subfolder 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 contents of the Dart Sass archive file 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 lines:export PATH="$HOME/bin:$PATH" export PATH="$HOME/bin/dart-sass:$PATH"
Restart the terminal app, and check that
PATH
now includes your entries:echo $PATH
Get the archive file
Navigate to your default downloads destination,
/Users/JohnDoe/Downloads/
.To get the latest version of Dart Sass, go to its GitHub releases page and download the corresponding
tar.gz
archive file for your particular system architecture:- Apple Silicon (
macos-arm64
) - Intel (
macos-x64
)
- Apple Silicon (
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, you can double-click the.tar.gz
file in the Finder.)
The resulting contents should be as shown inside your downloads folder:Even though it lacks an extension,dart-sass └─ dart-sass-embedded └─ src └─ dart └─ LICENSE └─ sass.snapshot
dart-sass/sass
is a shell script that works with the actual binary,dart-sass/src/dart
.
Move the dart-sass
folder to bin
Note: If you’ve done this before and already have a dart-sass
folder 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/dart-sass $HOME/bin/dart-sass
Confirm dart-sass
is in the PATH
Finally, to confirm that the dart-sass
folder and its contents are in the PATH
, enter the following in your terminal app:
sass --embedded --version
This will run the sass
shell script included in the sass_embedded
folder. The result should look something like this example from Dart Sass v.1.63.4:
{
"protocolVersion": "2.1.0",
"compilerVersion": "1.63.4",
"implementationVersion": "1.63.4",
"implementationName": "Dart Sass",
"id": 0
}
If you get any other kind of response, it means the dart-sass
folder 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. I hope this has spared you some searching. If you encounter errors in any of the above information, please let me know so I can fix it ASAP!
Reminder: In a worst-case scenario in which you can’t get this to work no matter what you do, there’s always the option of using the Node.js Sass package, instead, as I described in the original article in this series. It’s not quite as elegant for Hugo’s purposes, and it definitely is slower than using the Dart Sass binary, but it works.
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 and subfolder 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 contents of the Dart Sass archive file 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 Run as administrator again.
- In Command Prompt, enter:
setx PATH "C:\Users\JohnDoe\bin\dart-sass;%PATH%"
- Repeat step 2–3 to reload Command Prompt (with or without Run as administrator this time) and check the
PATH
to confirm your new entries are there:echo %PATH%
Get the archive file
Navigate to your default downloads destination,
C:\Users\JohnDoe\Downloads\
.To get the latest version of Dart Sass, go to its GitHub releases page and download the corresponding
tar.gz
archive file for your particular system architecture:- x64 (
windows-x64
) - IA-32 (
windows-ia32
)
- x64 (
In the Windows Taskbar search box, search for
cmd
.Open
Command Prompt
(with or withoutRun as administrator
).In Command Prompt, enter
tar -xf
followed by the name of the.tar.gz
file.
The resulting contents should be as shown (inside the regular downloads folder):Thedart-sass └─ sass.bat └─ src └─ dart.exe └─ LICENSE └─ sass.snapshot
dart-sass\sass.bat
batch file works with the actual binary,dart-sass\src\dart.exe
.
Move the dart-sass
folder to bin
Note: If you’ve done this before and already have a dart-sass
folder within bin
, you do want to delete the existing one in favor of what you’ll be moving below.
Enter the following in Command Prompt:
move C:\Users\JohnDoe\Downloads\dart-sass C:\Users\JohnDoe\bin\dart-sass
Confirm dart-sass
is in the PATH
Finally, to confirm that the dart-sass
folder and its contents are in the PATH
, enter the following in Command Prompt:
sass --embedded --version
This will run the sass.bat
batch file included in the dart-sass
folder. The result should look something like this example from Dart Sass v.1.63.4:
{
"protocolVersion": "2.1.0",
"compilerVersion": "1.63.4",
"implementationVersion": "1.63.4",
"implementationName": "Dart Sass",
"id": 0
}
If you get any other kind of response, it means the dart-sass
folder 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. I hope this has spared you some searching. If you encounter errors in any of the above information, please let me know so I can fix it ASAP!
Reminder: In a worst-case scenario in which you can’t get this to work no matter what you do, there’s always the option of using the Node.js Sass package, instead, as I described in the original article in this series. It’s not quite as elegant for Hugo’s purposes, and it definitely is slower than using the Dart Sass binary, but it works.
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