Dart Sass Command-Line Interface
UsageUsage permalink
The Dart Sass executable can be invoked in one of two modes.
One-to-One ModeOne-to-One Mode permalink
sass <input.scss> [output.css]
One-to-one mode compiles a single input file (input.scss) to a single output
location (output.css). If no output location is passed, the compiled CSS is
printed to the terminal.
The input file is parsed as SCSS if its extension is .scss, as the
indented syntax if its extension is .sass, or as plain CSS if its
extension is .css. If it doesn’t have one of these three extensions, or if it
comes from standard input, it’s parsed as SCSS by default. This can be
controlled with the --indented flag.
The special string - can be passed in place of the input file to tell Sass to
read the input file from standard input. Sass will default to parsing it as
SCSS unless the --indented flag is passed.
Many-to-Many ModeMany-to-Many Mode permalink
- Dart Sass
- since 1.4.0
sass [<input.scss>:<output.css>] [<input/>:<output/>]...
Many-to-many mode compiles one or more input files to one or more output files. The inputs are separated from the outputs with colons. It can also compile all Sass files in a directory to CSS files with the same names in another directory.
β# Compiles style.scss to style.css.
$ sass style.scss:style.css
β# Compiles light.scss and dark.scss to light.css and dark.css.
$ sass light.scss:light.css dark.scss:dark.css
β# Compiles all Sass files in themes/ to CSS files in public/css/.
$ sass themes:public/cssWhen compiling whole directories, Sass will ignore partial files whose names
begin with _. You can use partials to separate out your stylesheets without
creating a bunch of unnecessary output files.
OptionsOptions permalink
Input and OutputInput and Output permalink
These options control how Sass loads its input files and how it produces output files.
--stdin–stdin permalink
This flag is an alternative way of telling Sass that it should read its input file from standard input. When it’s passed, no input file may be passed.
$ echo "h1 {font-size: 40px}" | sass --stdin h1.css
$ echo "h1 {font-size: 40px}" | sass --stdin
h1 {
font-size: 40px;
}
The --stdin flag may not be used with many-to-many mode.
--indented–indented permalink
This flag tells Sass to parse the input file as the indented syntax. If it’s
used in many-to-many mode, all input files are parsed as the indented
syntax, although files they use will have their syntax determined as usual.
The inverse, --no-indented, can be used to force all input files to be parsed
as SCSS instead.
The --indented flag is mostly useful when the input file is coming from
standard input, so its syntax can’t be automatically determined.
$ echo -e 'h1\n font-size: 40px' | sass --indented -
h1 {
font-size: 40px;
}
--load-path–load-path permalink
This option (abbreviated -I) adds an additional load path for Sass to look
for stylesheets. It can be passed multiple times to provide multiple load paths.
Earlier load paths will take precedence over later ones.
$ sass --load-path=node_modules/bootstrap/dist/css style.scss style.css--pkg-importer=node–pkg-importer=node permalink
- Dart Sass
- since 1.71.0
This option (abbreviated -p node) adds the Node.js pkg: importer to the
end of the load path, so that stylesheets can load dependencies using the
Node.js module resolution algorithm.
Support for additional built-in pkg: importers may be added in the future.
$ sass --pkg-importer=node style.scss style.css--style–style permalink
This option (abbreviated -s) controls the output style of the resulting CSS.
Dart Sass supports two output styles:
expanded(the default) writes each selector and declaration on its own line.compressedremoves as many extra characters as possible, and writes the entire stylesheet on a single line.
$ sass --style=expanded style.scss
h1 {
font-size: 40px;
}
$ sass --style=compressed style.scss
h1{font-size:40px}
--no-charset–no-charset permalink
- Dart Sass
- since 1.19.0
This flag tells Sass never to emit a @charset declaration or a UTF-8
byte-order mark. By default, or if --charset is passed, Sass will insert
either a @charset declaration (in expanded output mode) or a byte-order mark
(in compressed output mode) if the stylesheet contains any non-ASCII characters.
$ echo 'h1::before {content: "π"}' | sass --no-charset
h1::before {
content: "π";
}
$ echo 'h1::before {content: "π"}' | sass --charset
@charset "UTF-8";
h1::before {
content: "π";
}
--error-css–error-css permalink
- Dart Sass
- since 1.20.0
This flag tells Sass whether to emit a CSS file when an error occurs during
compilation. This CSS file describes the error in a comment and in the
content property of body::before, so that you can see the error message in
the browser without needing to switch back to the terminal.
By default, error CSS is enabled if you’re compiling to at least one file on
disk (as opposed to standard output). You can pass --error-css explicitly to
enable it even when you’re compiling to standard out, or --no-error-css to
disable it everywhere. When it’s disabled, the --update flag and
--watch flag will delete CSS files instead when an error occurs.
$ sass --error-css style.scss style.css
/* Error: Incompatible units em and px.
* ,
* 1 | $width: 15px + 2em;
* | ^^^^^^^^^^
* '
* test.scss 1:9 root stylesheet */
body::before {
font-family: "Source Code Pro", "SF Mono", Monaco, Inconsolata, "Fira Mono",
"Droid Sans Mono", monospace, monospace;
white-space: pre;
display: block;
padding: 1em;
margin-bottom: 1em;
border-bottom: 2px solid black;
content: "Error: Incompatible units em and px.\a \2577 \a 1 \2502 $width: 15px + 2em;\a \2502 ^^^^^^^^^^\a \2575 \a test.scss 1:9 root stylesheet";
}
Error: Incompatible units em and px.
β·
1 β $width: 15px + 2em;
β ^^^^^^^^^^
β΅
test.scss 1:9 root stylesheet
--update–update permalink
- Dart Sass
- since 1.4.0
If the --update flag is passed, Sass will only compile stylesheets whose
dependencies have been modified more recently than the corresponding CSS file
was generated. It will also print status messages when updating stylesheets.
$ sass --update themes:public/css
Compiled themes/light.scss to public/css/light.css.
Source MapsSource Maps permalink
- Dart Sass
- since 1.3.0
Source maps are files that tell browsers or other tools that consume CSS how that CSS corresponds to the Sass files from which it was generated. They make it possible to see and even edit your Sass files in browsers. See instructions for using source maps in Chrome and Firefox.
Dart Sass generates source maps by default for every CSS file it emits.
--no-source-map–no-source-map permalink
If the --no-source-map flag is passed, Sass won’t generate any source maps. it
cannot be passed along with other source map options.
$ sass --no-source-map style.scss style.css--source-map-urls–source-map-urls permalink
This option controls how the source maps that Sass generates link back to the Sass files that contributed to the generated CSS. Dart Sass supports two types of URLs:
relative(the default) uses relative URLs from the location of the source map file to the locations of the Sass source file.absoluteuses the absolutefile:URLs of the Sass source files. Note that absolute URLs will only work on the same computer that the CSS was compiled.
β# Generates a URL like "../sass/style.scss".
$ sass --source-map-urls=relative sass/style.scss css/style.css
β# Generates a URL like "file:///home/style-wiz/sassy-app/sass/style.scss".
$ sass --source-map-urls=absolute sass/style.scss css/style.css--embed-sources–embed-sources permalink
This flag tells Sass to embed the entire contents of the Sass files that contributed to the generated CSS in the source map. This may produce very large source maps, but it guarantees that the source will be available on any computer no matter how the CSS is served.
$ sass --embed-sources sass/style.scss css.style.css--embed-source-map–embed-source-map permalink
This flag tells Sass to embed the contents of the source map file in the generated CSS, rather than creating a separate file and linking to it from the CSS.
$ sass --embed-source-map sass/style.scss css.style.cssOther OptionsOther Options permalink
--watch–watch permalink
- Dart Sass
- since 1.6.0
This flag (abbreviated -w) acts like the --update flag, but after the
first round compilation is done Sass stays open and continues compiling
stylesheets whenever they or their dependencies change.
Sass watches only the directories that you pass as-is on the command line,
parent directories of filenames you pass on the command line, and load paths. It
does not watch additional directories based on a file’s @import/@use/
@forward rules.
$ sass --watch themes:public/css
Compiled themes/light.scss to public/css/light.css.
β# Then when you edit themes/dark.scss...
Compiled themes/dark.scss to public/css/dark.css.
--poll–poll permalink
- Dart Sass
- since 1.8.0
This flag, which may only be passed along with --watch, tells Sass to manually
check for changes to the source files every so often instead of relying on the
operating system to notify it when something changes. This may be necessary if
you’re editing Sass on a remote drive where the operating system’s notification
system doesn’t work.
$ sass --watch --poll themes:public/css
Compiled themes/light.scss to public/css/light.css.
β# Then when you edit themes/dark.scss...
Compiled themes/dark.scss to public/css/dark.css.
--stop-on-error–stop-on-error permalink
- Dart Sass
- since 1.8.0
This flag tells Sass to stop compiling immediately when an error is detected, rather than trying to compile other Sass files that may not contain errors. It’s mostly useful in many-to-many mode.
$ sass --stop-on-error themes:public/css
Error: Expected expression.
β·
42 β h1 {font-face: }
β ^
β΅
themes/light.scss 42:16 root stylesheet
--interactive–interactive permalink
- Dart Sass
- since 1.5.0
This flag (abbreviated -i) tells Sass to run in interactive mode, where you
can write SassScript expressions and see their results. Interactive mode
also supports variables and @use rules.
$ sass --interactive
>> 1px + 1in
97px
>> @use "sass:map"
>> $map: ("width": 100px, "height": 70px)
("width": 100px, "height": 70px)
>> map.get($map, "width")
100px
--color–color permalink
This flag (abbreviated -c) tells Sass to emit terminal colors, and the
inverse --no-color tells it not to emit colors. By default, it will emit
colors if it looks like it’s being run on a terminal that supports them.
$ sass --color style.scss style.css
Error: Incompatible units em and px.
β·
1 β $width: 15px + 2em
β ^^^^^^^^^^
β΅
style.scss 1:9 root stylesheet
$ sass --no-color style.scss style.css
Error: Incompatible units em and px.
β·
1 β $width: 15px + 2em
β ^^^^^^^^^^
β΅
style.scss 1:9 root stylesheet--no-unicode–no-unicode permalink
- Dart Sass
- since 1.17.0
This flag tells Sass only to emit ASCII characters to the terminal as part of
error messages. By default, or if --unicode is passed, Sass will emit non-ASCII
characters for these messages. This flag does not affect the CSS output.
$ sass --no-unicode style.scss style.css
Error: Incompatible units em and px.
,
1 | $width: 15px + 2em;
| ^^^^^^^^^^
'
test.scss 1:9 root stylesheet
$ sass --unicode style.scss style.css
Error: Incompatible units em and px.
β·
1 β $width: 15px + 2em;
β ^^^^^^^^^^
β΅
test.scss 1:9 root stylesheet
--verbose–verbose permalink
This flag tells Sass to emit all deprecation warnings when compiling. By default, Sass only emits five warnings for a given deprecation type when deprecated features are used, and silences any warnings beyond that.
$ sass --verbose style.scss style.css--quiet–quiet permalink
This flag (abbreviated -q) tells Sass not to emit any warnings when compiling.
By default, Sass emits warnings when deprecated features are used or when the
@warn rule is encountered. It also silences the @debug rule.
$ sass --quiet style.scss style.css--quiet-deps–quiet-deps permalink
This flag tells Sass not to emit deprecation warnings that come from
dependencies. It considers any file that’s transitively imported through a load
path to be a "dependency". This flag doesn’t affect the @warn rule or the
@debug rule.
$ sass --load-path=node_modules --quiet-deps style.scss style.css--fatal-deprecation–fatal-deprecation permalink
- Dart Sass
- since 1.59.0
This option tells Sass to treat a particular type of deprecation warning as
an error. For example, this command tells Sass to treat deprecation
warnings for /-as-division as errors:
$ sass --fatal-deprecation=slash-div style.scss style.css
Error: Using / for division outside of calc() is deprecated and will be removed in Dart Sass 2.0.0.
Recommendation: math.div(4, 2) or calc(4 / 2)
More info and automated migrator: /documentation/breaking-changes/slash-div
This is only an error because you've set the slash-div deprecation to be fatal.
Remove this setting if you need to keep using this feature.
β·
1 β a { b: (4/2); }
β ^^^
β΅
style.scss 1:9 root stylesheet
The following deprecation IDs can be passed to this option:
| ID | Deprecated In | Description |
|---|---|---|
call-string | 0.0.0 | Passing a string directly to meta.call(). |
elseif | 1.3.2 | @elseif. |
moz-document | 1.7.2 | @-moz-document. |
relative-canonical | 1.14.2 | Imports using relative canonical URLs. |
new-global | 1.17.2 | Declaring new variables with !global. |
color-module-compat | 1.23.0 | Using color module functions in place of plain CSS functions. |
slash-div | 1.33.0 | / operator for division. |
bogus-combinators | 1.54.0 | Leading, trailing, and repeated combinators. |
strict-unary | 1.55.0 | Ambiguous + and - operators. |
function-units | 1.56.0 | Passing invalid units to built-in functions. |
duplicate-var-flags | 1.62.0 | Using !default or !global multiple times for one variable. |
null-alpha | 1.62.3 | Passing null as alpha in the JS API. |
abs-percent | 1.65.0 | Passing percentages to the Sass abs() function. |
fs-importer-cwd | 1.73.0 | Using the current working directory as an implicit load path. |
css-function-mixin | 1.76.0 | Function and mixin names beginning with –. |
mixed-decls | 1.77.7 | Declarations after or between nested rules. |
feature-exists | 1.78.0 | meta.feature-exists |
color-4-api | 1.79.0 | Certain uses of built-in sass:color functions. |
color-functions | 1.79.0 | Using global color functions instead of sass:color. |
legacy-js-api | 1.79.0 | Legacy JS API. |
import | 1.80.0 | @import rules. |
global-builtin | 1.80.0 | Global built-in functions that are available in sass: modules. |
Alternatively, you can pass a Dart Sass version to treat all deprecations that
were present in that version as errors. For example,
--fatal-deprecation=1.33.0 would treat all deprecations in the
table above up to and including slash-div as errors, but leave any newer
deprecations as warnings.
--future-deprecation–future-deprecation permalink
- Dart Sass
- since 1.59.0
This option tells Sass to opt-in to a future type of deprecation warning
early, emitting warnings even though the deprecation is not yet active. This
option can be combined with --fatal-deprecation to emit errors instead of
warnings for a future deprecation.
$ sass --future-deprecation=import style.scss style.css
Deprecation Warning on line 1, column 9 of style.scss:
Sass @import rules will be deprecated in the future.
Remove the --future-deprecation=import flag to silence this warning for now.
β·
1 β @import 'dependency';
β ^^^^^^^^^^^^
β΅
There are no future deprecations in the latest version of Dart Sass.
--silence-deprecation–silence-deprecation permalink
- Dart Sass
- since 1.74.0
This option tells Sass to silence a particular type of deprecation warning if
you wish to temporarily ignore the deprecation. Any of the deprecations listed
in the --fatal-deprecation section above can be passed here, though passing
in a version is not supported.
$ sass --silence-deprecation=slash-div style.scss style.css--trace–trace permalink
This flag tells Sass to print the full Dart or JavaScript stack trace when an error is encountered. It’s used by the Sass team for debugging errors.
$ sass --trace style.scss style.css
Error: Expected expression.
β·
42 β h1 {font-face: }
β ^
β΅
themes/light.scss 42:16 root stylesheet
package:sass/src/visitor/evaluate.dart 1846:7 _EvaluateVisitor._addExceptionSpan
package:sass/src/visitor/evaluate.dart 1128:12 _EvaluateVisitor.visitBinaryOperationExpression
package:sass/src/ast/sass/expression/binary_operation.dart 39:15 BinaryOperationExpression.accept
package:sass/src/visitor/evaluate.dart 1097:25 _EvaluateVisitor.visitVariableDeclaration
package:sass/src/ast/sass/statement/variable_declaration.dart 50:15 VariableDeclaration.accept
package:sass/src/visitor/evaluate.dart 335:13 _EvaluateVisitor.visitStylesheet
package:sass/src/visitor/evaluate.dart 323:5 _EvaluateVisitor.run
package:sass/src/visitor/evaluate.dart 81:10 evaluate
package:sass/src/executable/compile_stylesheet.dart 59:9 compileStylesheet
package:sass/src/executable.dart 62:15 main
--help–help permalink
This flag (abbreviated -h) prints a summary of this documentation.
$ sass --help
Compile Sass to CSS.
Usage: sass <input.scss> [output.css]
sass <input.scss>:<output.css> <input/>:<output/>
...
--version–version permalink
This flag prints the current version of Sass.
$ sass --version
1.80.7