# Using the Dart Sass transpiler

**URL:** <https://discourse.gohugo.io/t/using-the-dart-sass-transpiler/41878>\
**Category:** tips & tricks\
**Tags:** sass, dart-sass\
**Created:** [December 12, 2022, 11:03pm UTC](https://discourse.gohugo.io/t/using-the-dart-sass-transpiler/41878 "2022-12-12T23:03:00Z")\
**Posts on this page:** 16\
**Page:** 1

<div class="post-metadata">

**Author:** ![jmooring](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jmooring/32/4214_2.png) [@jmooring](https://discourse.gohugo.io/u/jmooring)\
**Post date:** [December 12, 2022, 11:03pm UTC](https://discourse.gohugo.io/t/using-the-dart-sass-transpiler/41878/1 "2022-12-12T23:03:00Z")

</div>

Last updated: 2023-06-22T17:38:47-07:00

This information is now included in the [Hugo documentation](https://gohugo.io/functions/resources/tocss/#dart-sass).

* * *

The extended version of Hugo includes [LibSass](https://sass-lang.com/libsass) to transpile Sass to CSS. In 2020, the Sass team deprecated LibSass in favor of [Dart Sass](https://sass-lang.com/dart-sass).

Use the latest features of the Sass language by installing Dart Sass in your development and production environments.

### Installation overview

Dart Sass is compatible with Hugo v0.114.0 and later.

If you have been using Embedded Dart Sass\[1\] with Hugo v0.113.0 and earlier, uninstall Embedded Dart Sass, then install Dart Sass. If you have installed both, Hugo will use Dart Sass.

If you install Hugo as a [Snap package](https://gohugo.io/installation/linux/#snap) there is no need to install Dart Sass. The Hugo Snap package includes Dart Sass.

### Installing in a development environment

When you install Dart Sass somewhere in your PATH, Hugo will find it.

| OS | Package manager | Site | Installation |
| --- | --- | --- | --- |
| Linux | Homebrew | [brew.sh](https://brew.sh/) | `brew install sass/sass/sass` |
| Linux | Snap | [snapcraft.io](https://snapcraft.io/dart-sass) | `sudo snap install dart-sass` |
| macOS | Homebrew | [brew.sh](https://brew.sh/) | `brew install sass/sass/sass` |
| Windows | Chocolatey | [chocolatey.org](https://community.chocolatey.org/packages/sass) | `choco install sass` |
| Windows | Scoop | [scoop.sh](https://scoop.sh/#/apps?q=sass) | `scoop install sass` |

You may also install [prebuilt binaries](https://github.com/sass/dart-sass/releases/latest) for Linux, macOS, and Windows.

Run `hugo env` to list the active transpilers.

### Installing in a production environment

For [CI/CD](https://en.wikipedia.org/wiki/CI/CD) deployments (e.g., GitHub Pages, GitLab Pages, Netlify, etc.) you must edit the workflow to install Dart Sass before Hugo builds the site\[2\]. Some providers allow you to use one of the package managers above, or you can download and extract one of the prebuilt binaries.

#### GitHub Pages

To install Dart Sass for your builds on GitHub Pages, add this step to the GitHub Pages workflow file:

```yaml
- name: Install Dart Sass
  run: sudo snap install dart-sass

```

If you are using GitHub Pages for the first time with your repository, GitHub provides a [starter workflow](https://github.com/actions/starter-workflows/blob/main/pages/hugo.yml) for Hugo that includes Dart Sass. This is the simplest way to get started.

#### GitLab Pages

To install Dart Sass for your builds on GitLab Pages, the `.gitlab-ci.yml` file should look something like this:

```yaml
variables:
  HUGO_VERSION: 0.114.0
  DART_SASS_VERSION: 1.63.5
  GIT_DEPTH: 0
  GIT_STRATEGY: clone
  GIT_SUBMODULE_STRATEGY: recursive
  TZ: America/Los_Angeles
image:
  name: golang:1.20-buster
pages:
  script:
    # Install Dart Sass
    - curl -LJO https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
    - tar -xf dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
    - cp -r dart-sass/* /usr/local/bin
    - rm -rf dart-sass*
    # Install Hugo
    - curl -LJO https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb
    - apt install -y ./hugo_extended_${HUGO_VERSION}_linux-amd64.deb
    - rm hugo_extended_${HUGO_VERSION}_linux-amd64.deb
    # Build
    - hugo --gc --minify
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

```

#### Netlify

To install Dart Sass for your builds on Netlify, the `netlify.toml` file should look something like this:

```toml
[build.environment]
HUGO_VERSION = "0.114.0"
DART_SASS_VERSION = "1.63.5"
TZ = "America/Los_Angeles"

[build]
publish = "public"
command = """\
  curl -LJO https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \
  tar -xf dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \
  rm dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \
  export PATH=/opt/build/repo/dart-sass:$PATH && \
  hugo --gc --minify \
  """

```

### Example

To tranpile with Dart Sass, set `transpiler` to `dartsass` in the options map passed to `resources.ToCSS`. For example:

```go-html-template
{{ $opts := dict "transpiler" "dartsass" "targetPath" "css/style.css" }}
{{ with resources.Get "sass/main.scss" | toCSS $opts | minify | fingerprint }}
  <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
{{ end }}

```

### Miscellaneous

If you build Hugo from source and run `mage test -v`, the test will fail if you install Dart Sass as a Snap package. This is due to the Snap package’s strict confinement model.

* * *

1. In 2023, the Sass team deprecated Embedded Dart Sass in favor of Dart Sass. 

2. You do not have to do this if (a) you have not modified the assets cache location, and (b) you have not set `useResourceCacheWhen` to `never` in your [site configuration](https://gohugo.io/getting-started/configuration/#configure-build), and (c) you add and commit your resources directory to your repository.

---

<div class="post-metadata">

**Author:** ![Horbes](https://avatars.discourse-cdn.com/v4/letter/h/a9adbd/32.png) [@Horbes](https://discourse.gohugo.io/u/Horbes)\
**Post date:** [February 11, 2023, 7:29am UTC](https://discourse.gohugo.io/t/using-the-dart-sass-transpiler/41878/2 "2023-02-11T07:29:20Z")

</div>

Thanks for this. A really handy and easy to follow guide and thankfully a pain free switch to using Dart sass.

I was already finding some of the newer CSS, like the min() function, was causing errors using libsass and with all the new CSS coming out over the past year or so such problems/limitations would only have increased.

Still, although simple, hopefully Dart sass is integrated into Hugo in the near future. That single binary simplicity was one of the main attractions for me when I first started using Hugo.

---

<div class="post-metadata">

**Author:** ![frjo](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/frjo/32/18626_2.png) [@frjo](https://discourse.gohugo.io/u/frjo)\
**Post date:** [February 11, 2023, 11:03am UTC](https://discourse.gohugo.io/t/using-the-dart-sass-transpiler/41878/3 "2023-02-11T11:03:48Z")

</div>

Excellent guide!

The css min() and sass min() etc. can clash, a simple solution is to write Min() if you want the css version. sass is case sensitive but css is not.

---

<div class="post-metadata">

**Author:** ![bwintx](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/bwintx/32/10450_2.png) [@bwintx](https://discourse.gohugo.io/u/bwintx)\
**Post date:** [June 20, 2023, 12:52pm UTC](https://discourse.gohugo.io/t/using-the-dart-sass-transpiler/41878/4 "2023-06-20T12:52:56Z")

</div>

Given the compatibility of Hugo 0.114.0+ with how Embedded Dart Sass is packaged within the Dart Sass binary as of Dart Sass 1.63.0, would your instructions for everything other than the Hugo Snap package now be the same **except** for installing `dart-sass` rather than `dart-sass-embedded` (or `dart-sass-embedded@1.62.1` in the case of Homebrew)?

---

<div class="post-metadata">

**Author:** ![jmooring](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jmooring/32/4214_2.png) [@jmooring](https://discourse.gohugo.io/u/jmooring)\
**Post date:** [June 20, 2023, 1:54pm UTC](https://discourse.gohugo.io/t/using-the-dart-sass-transpiler/41878/5 "2023-06-20T13:54:33Z")

</div>

I have a checklist of items to update, including this Tips & Tricks article. But there’s no rush. I would prefer to wait until things settle down on the Sass side. Their changes were… abrupt.

---

<div class="post-metadata">

**Author:** ![jmooring](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jmooring/32/4214_2.png) [@jmooring](https://discourse.gohugo.io/u/jmooring)\
**Post date:** [June 21, 2023, 8:04am UTC](https://discourse.gohugo.io/t/using-the-dart-sass-transpiler/41878/6 "2023-06-21T08:04:21Z")

</div>

I’ve edited the original posting to reflect the transition from Embedded Dart Sass to Dart Sass.

---

<div class="post-metadata">

**Author:** ![bwintx](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/bwintx/32/10450_2.png) [@bwintx](https://discourse.gohugo.io/u/bwintx)\
**Post date:** [June 21, 2023, 10:12am UTC](https://discourse.gohugo.io/t/using-the-dart-sass-transpiler/41878/7 "2023-06-21T10:12:27Z")

</div>

Yes, I see, here and in [#1921](https://github.com/gohugoio/hugoDocs/issues/1921). Good show! 👍

---

<div class="post-metadata">

**Author:** ![bradbice](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/bradbice/32/14162_2.png) [@bradbice](https://discourse.gohugo.io/u/bradbice)\
**Post date:** [June 27, 2023, 10:11pm UTC](https://discourse.gohugo.io/t/using-the-dart-sass-transpiler/41878/8 "2023-06-27T22:11:07Z")

</div>

I had to fix my Dart SDK by using (use at your own need/risk):

```auto
brew tap --repair
brew remove dart
brew update
brew install dart-lang/dart/dart
brew install sass/sass/sass

```

Now `hugo env` shows this:

```auto
hugo v0.114.1+extended darwin/arm64 BuildDate=unknown
GOOS="darwin"
GOARCH="arm64"
GOVERSION="go1.20.5"
github.com/sass/libsass="3.6.5"
github.com/webmproject/libwebp="v1.2.4"
github.com/sass/dart-sass/protocol="2.1.0"
github.com/sass/dart-sass/compiler="1.63.6"
github.com/sass/dart-sass/implementation="1.63.6"

```

Why is `libsass` still referenced? Is that ok? My hugo build seems fine…

---

<div class="post-metadata">

**Author:** ![jmooring](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jmooring/32/4214_2.png) [@jmooring](https://discourse.gohugo.io/u/jmooring)\
**Post date:** [June 27, 2023, 10:13pm UTC](https://discourse.gohugo.io/t/using-the-dart-sass-transpiler/41878/9 "2023-06-27T22:13:35Z")

</div>

> [@bradbice](#):
>
> Why is `libsass` still referenced?

Because it is built-in to the extended edition.

> [@bradbice](#):
>
> Is that ok?

Yes.

> [@bradbice](#):
>
> I had to fix my Dart SDK

Yes, I saw a brew/sass issue about this somewhere. Not our problem.

---

<div class="post-metadata">

**Author:** ![bwintx](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/bwintx/32/10450_2.png) [@bwintx](https://discourse.gohugo.io/u/bwintx)\
**Post date:** [June 29, 2023, 7:11pm UTC](https://discourse.gohugo.io/t/using-the-dart-sass-transpiler/41878/10 "2023-06-29T19:11:38Z")

</div>

Another possibility — a shell script for installing both Hugo **and** Dart Sass on macOS or Linux/WSL (no PowerPoint version, sorry):

> **[Using Dart Sass with Hugo: a simpler way | BryceWray.com](https://www.brycewray.com/posts/2023/06/using-dart-sass-hugo-simpler-way/)**
>
> A shell script based on my GitHub Action suddenly makes it a breeze to install both Hugo and Dart Sass.

---

<div class="post-metadata">

**Author:** ![jmooring](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jmooring/32/4214_2.png) [@jmooring](https://discourse.gohugo.io/u/jmooring)\
**Post date:** [September 27, 2023, 10:33pm UTC](https://discourse.gohugo.io/t/using-the-dart-sass-transpiler/41878/11 "2023-09-27T22:33:53Z")

</div>

2 posts were split to a new topic: [Help with Dart Sass installation on Mac](https://discourse.gohugo.io/t/help-with-dart-sass-installation-on-mac/46449)

---

<div class="post-metadata">

**Author:** ![richard\_hugo](https://avatars.discourse-cdn.com/v4/letter/r/71e660/32.png) [@richard\_hugo](https://discourse.gohugo.io/u/richard_hugo)\
**Post date:** [November 16, 2023, 4:03pm UTC](https://discourse.gohugo.io/t/using-the-dart-sass-transpiler/41878/12 "2023-11-16T16:03:35Z")

</div>

I wondered if it would be worth adding to the list the option on Linux of installing [sass-embedded - npm](https://www.npmjs.com/package/sass-embedded) which as I understand it includes the dart build of dart-sass (the naming scheme does seem somewhat byzantine). It does then need the PATH manually setting to point to the package in node\_modules (e.g. node\_modules/sass-embedded-linux-x64/dart-sass) but the advantage for us is that it’s managed by npm / package.json for updating, as we cannot use snap or brew on our production servers.

---

<div class="post-metadata">

**Author:** ![jmooring](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jmooring/32/4214_2.png) [@jmooring](https://discourse.gohugo.io/u/jmooring)\
**Post date:** [November 16, 2023, 6:38pm UTC](https://discourse.gohugo.io/t/using-the-dart-sass-transpiler/41878/13 "2023-11-16T18:38:35Z")

</div>

I didn’t know this package was available again.

When the Dart Sass team changed the embedded protocol in 1.63.0, they did not roll a release for [Embedded Sass Host](https://github.com/sass/embedded-host-node), also known as embedded-host-node, or sass-embedded in the npm registry. Nor did they roll a release for 1.63.1, so I concluded this package was abandoned along with the dart-sass-embedded Homebrew package, which was a bit of a mess.

As you described, the ` npm install sass-embedded` command does not place the “binary” in your PATH. Similar to using `curl` on GitLab as shown in our [Dart Sass](https://gohugo.io/functions/resources/tocss/#gitlab-pages) documentation, you may have to move the “binary” to a location already in your path, or modify the PATH variable.

I quote the word “binary” because it’s not a binary. It’s a script (batch file on Windows) that calls Dart, passing the path to the sass.snapshot file as an argument. This file structure is the same across for all Dart Sass implementations, excluding the [Dart Sass npm package](https://github.com/sass/dart-sass#from-npm), which doesn’t support the embedded protocol.

Given the history here, I am reluctant to document this approach, and it definitely should not be documented as an alternative to the the package managers.

In your case, I think the safest (best chances of forward compatibility) approach is to use `curl` to download [Dart Sass](https://github.com/sass/dart-sass). Again, see [this example](https://gohugo.io/functions/resources/tocss/#gitlab-pages).

---

<div class="post-metadata">

**Author:** ![Hentioe](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/hentioe/32/20984_2.png) [@Hentioe](https://discourse.gohugo.io/u/Hentioe)\
**Post date:** [June 6, 2024, 8:17pm UTC](https://discourse.gohugo.io/t/using-the-dart-sass-transpiler/41878/14 "2024-06-06T20:17:03Z")

</div>

If you use mise to manage dart-sass, Hugo will fail to start.

This is `.mise.toml`

```auto
[tools]
"npm:dart-sass" = "latest"

```

This is the output:

```auto
$ dart-sass --version
1.25.0 compiled with dart2js 2.7.0

$ which dart-sass
/home/hentioe/.local/share/mise/shims/dart-sass

$ hugo server -D
port 1313 already in use, attempting to use an available port
Watching for changes in /home/hentioe/code/hugo-blog/{archetypes,assets,content,data,i18n,layouts,package.json,static,themes}
Watching for config changes in /home/hentioe/code/hugo-blog/hugo.toml, /home/hentioe/code/hugo-blog/themes/my-theme/hugo.toml
Start building sites … 
hugo v0.127.0 linux/amd64 BuildDate=unknown

Built in 155 ms
Error: error building site: TOCSS-DART: failed to transform "/scss/main.scss" (text/x-scss): "<stream>:1:1": proto: cannot parse invalid wire-format data

```

[mise](https://mise.jdx.dev/) is a version management tool similar to asdf that can manage NPM package versions without the need for `package.json` or `npm i -g`.

I know mise isn’t a very common tool, but it would be nice if it could be fixed.

---

<div class="post-metadata">

**Author:** ![frjo](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/frjo/32/18626_2.png) [@frjo](https://discourse.gohugo.io/u/frjo)\
**Post date:** [June 7, 2024, 7:57am UTC](https://discourse.gohugo.io/t/using-the-dart-sass-transpiler/41878/15 "2024-06-07T07:57:47Z")

</div>

Hugo needs the embedded Sass protocol and that is not included in the npm version.

> **[GitHub - sass/dart-sass: The reference implementation of Sass, written in Dart.](https://github.com/sass/dart-sass?tab=readme-ov-file#embedded-dart-sass)**
>
> The reference implementation of Sass, written in Dart. - sass/dart-sass

---

<div class="post-metadata">

**Author:** ![jmooring](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jmooring/32/4214_2.png) [@jmooring](https://discourse.gohugo.io/u/jmooring)\
**Post date:** [June 7, 2024, 12:37pm UTC](https://discourse.gohugo.io/t/using-the-dart-sass-transpiler/41878/16 "2024-06-07T12:37:14Z")

</div>

> [@Hentioe](#):
>
> but it would be nice if it could be fixed.

As @frjo described, there’s nothing to fix.