Scala Compiler Options



Scala compiler scalac offers various compiler options, also referred to as compiler flags, to change how to compile your program.

Nowadays, most people are not running scalac from the command line. Instead, they use sbt, an IDE, and other tools as their interface to the compiler. Therefore they may not even have scalac installed, and won’t think to do man scalac.

This page comes to the rescue for the people to find…

  • What compiler options scalac offers
  • How to use compiler options

How to use compiler options

Use compiler options with scalac

scalac [ <options> ] <source files>

E.g. scalac -encoding utf8 -Xfatal-warnings Hello.scala

Use compiler options with sbt

scalacOptions ++= Seq(
  "-encoding", "utf8", // Option and arguments on same line
  "-Xfatal-warnings",  // New lines for each options

Standard Settings

A set of standard options that are supported on the current development environment and will be supported in future releases.

-classpath PATH or -cp PATH

Specify where to find user class files.

Default: .

destination for generated classfiles.

Default: .

Ignore @specialize annotations.


Enable or disable language features: _ for all, -language:help to list choices.


Allow direct or indirect subclasses of scala.Dynamic


Allow postfix operator notation, such as 1 to 10 toList


Allow reflective access to members of structural types


Allow definition of implicit functions called views


Allow higher-kinded types


Existential types (besides wildcard types) can be written and inferred


Allow macro definition (besides implementation and application)

-release RELEASE

Compile for a specific version of the Java platform. Supported targets: 6, 7, 8, 9

-optimise or -optimize

Compiler flag for the optimizer in Scala 2.11


Generated value class method overrides an implementation.

-bootclasspath PATH

Override location of bootstrap class files.

Default: Defaults.scalaBootClassPath
-extdirs PATH

Override location of installed extensions.

Default: Defaults.scalaExtDirs
-javabootclasspath PATH

Override java boot classpath.

Default: Defaults.javaBootClassPath
-javaextdirs PATH

Override java extdirs classpath.

Default: Defaults.javaExtDirs
-sourcepath PATH

Specify location(s) of source files.

-dependencyfile FILE

Set dependency tracking file.

Default: .scala_dependencies

Emit warning and location for usages of deprecated APIs.

-encoding ENCODING

Specify character encoding used by source files.

Default: Properties.sourceEncoding

Explain type errors in more detail.


Emit warning and location for usages of features that should be imported explicitly.


Set level of generated debugging info. Choices: (none,source,line,vars,notailcalls), default: vars.

Default: vars

Print a synopsis of standard options


Generate no warnings.


Print program with Scala-specific features removed.


Target platform for object files. All JVM 1.5 - 1.7 targets are deprecated. Choices: (jvm-1.5,jvm-1.6,jvm-1.7,jvm-1.8), default: jvm-1.8.

Default: jvm-1.8

Enable additional warnings where generated code depends on assumptions.


Uniquely tag all identifiers in debugging output.


Utilize the java.class.path in classpath resolution.


Utilize the manifest in classpath resolution.


Output messages about what the compiler is doing.


Print product version and exit.

JVM Settings

Settings influencing the runtime system.


Pass flag directly to the runtime system.


Pass -Dproperty=value directly to the runtime system.


Do not use the boot classpath for the scala jars.

Plugin Settings


Pass an option to a plugin

Note: If you use sbt, compiler plugins support may be useful.

Advanced Settings

Options that starts with -X are maybe renamed or removed in future releases.


Print a synopsis of advanced options.


Wrap field accessors to throw an exception on uninitialized access.


Indicates user is a developer - issue warnings about anything which seems amiss


Generate no assertions or assumptions.

-Xelide-below ARG

Calls to @elidable methods are omitted if method priority is lower than argument

Default: Int.MinValue

Do not generate static forwarders in mirror classes.

-Xgenerate-phase-graph FILE

Generate the phase graphs (outputs .dot files) to


Show more detail on why some implicits are not applicable.


Print a message whenever an implicit conversion is inserted.


Print a message when a reflective method call is generated


Print a message when reification creates a free term.


Print a message when reification resorts to generating a free type.

-Xmax-classfile-name ARG

Maximum filename length for generated classes

Default: 255
Min: 72
Max: 255
-Xmaxerrs ARG

Maximum errors to print

Default: 100
-Xmaxwarns ARG

Maximum warnings to print

Default: 100
-Xmigration VERSION

Warn about constructs whose behavior may have changed since version.

Default: none

Disable handling of \u unicode escapes.


Do not use JLine for editing.


Verify generic signatures in generated bytecode.

-Xplugin PATHS1,PATHS2

Load a plugin from each classpath.

-Xplugin-disable PLUGIN1,PLUGIN2

Disable plugins by name.


Print a synopsis of loaded plugins.

-Xplugin-require PLUGIN1,PLUGIN2

Abort if a named plugin is not loaded.

-Xpluginsdir PATH

Path to search for plugin archives.

Default: Defaults.scalaPluginPath
-Xprint ARG

Print out program after phases

Note: See Compilation Phases

Print tree positions, as offsets.


Print tree types (debugging option).


Print all compiler arguments and exit.


Display a prompt after each error (debugging option).


Compiler stays resident: read source filenames from standard input.

-Xscript OBJECT

Treat the source file as a script and wrap it in a main method.

-Xmain-class PATH

Class for manifest’s Main-Class entry (only useful with -d jar)

-Xshow-class CLASS

Show internal representation of class.

-Xshow-object OBJECT

Show internal representation of object.


Print a synopsis of compiler phases.

-Xsource-reader CLASSNAME

Specify a custom method for reading source files.

-Xreporter CLASSNAME

Specify a custom reporter for compiler messages.


Don’t infer known-unsound types

-Xsource VERSION

Treat compiler input as Scala source for the specified version, see scala/bug#8126.

Default: 2.12.0

Don’t perform exhaustivity/unreachability analysis. Also, ignore @switch annotation.


Retains pre 2.10 behavior of less aggressive truncation of least upper bounds.


Generate forwarder methods in classes inhering concrete methods from traits. Default: true, help to list choices.

Default: true

Always generate mixin forwarders.


Generate mixin forwarders for JUnit-annotated methods (JUnit 4 does not support default methods).


Only generate mixin forwarders required for program correctness.


Configure XML parsing.: _ for all, -Xxml:help to list choices.


Convert PCData to Text and coalesce sibling nodes


Turn on future language features.

Deprecated: For in Scala 2.12 and earlier. In 2.13 all options previously enabled by -Xexperimental are enabled by default or removed.

Enable experimental extensions.

-Xmacro-settings OPTION1,OPTION2

Custom settings for macros.

Private Settings

Options with -Y prefix are more experimental and unstable than those with -X prefix.

Some without -Y prefix (e.g. -opt:** and -opt-inline-from) are also included, since such granular optimization-related options are changeable.

Those influencing to language semantics are likely to be deprecated in Scala 2.13 (see scala/scala-dev#430).


Print a synopsis of private options.


Allow member objects to be overridden.


Allow vars to be overridden.


Attempt to break cycles encountered during typing

-Ybrowse ARG

Browse the abstract syntax tree after phases

Note: See Compilation Phases
-Ycheck ARG

Check the tree at the end of phases

Note: See Compilation Phases
-Yshow ARG

(Requires -Xshow-class or -Xshow-object) Show after phases

Note: See Compilation Phases

Use compact tree printer when displaying trees.


Disable tab-completion in the REPL.


Increase the quantity of debugging output.


Resolve term conflicts. Choices: (package,object,error), default: error.

Default: error
-Ylog ARG

Log operations during phases


Output information about what classpath is being applied.


Suppress generation of generic signatures for Java.


Compile without importing scala., java.lang., or Predef.


Compile without importing Predef.


Do not adapt an argument list (either by inserting () or creating a tuple) to match the receiver.

-Yrecursion ARG

Set recursion depth used when locking symbols.

Default: 0
Min: 0
Max: 2147483647

(Requires -Xprint:) Print detailed ASTs in formatted form.


(Requires -Xprint:) Print detailed ASTs in compact form.


(Requires -Xprint:) Print stringifications along with detailed ASTs.


Print the AST symbol hierarchy after each phase.


Print abbreviated symbol kinds next to symbol names.


Print owner identifiers next to symbol names.

-Yskip ARG

Skip phases

Note: See Compilation Phases
-Ygen-asmp DIR

Generate a parallel output directory of .asmp files (ie ASM Textifier output).

-Ydump-classes DIR

Dump the generated bytecode to .class files (useful for reflective compilation that utilizes in-memory classloaders).

-Ystop-after ARG or -stop ARG

Stop after phases

Note: See Compilation Phases
-Ystop-before ARG

Stop before phases

Note: See Compilation Phases

Use range positions for syntax trees.

-Yvalidate-pos ARG

Validate positions after the given phases (implies -Yrangepos)

Note: -Yrangepos is enabled at the same time.
-Yshow-member-pos OUTPUT STYLE

Show start and end positions of members (implies -Yrangepos)

Note: -Yrangepos is enabled at the same time.

Dump the reified trees in copypasteable representation.


Control expansion of macros, useful for scaladoc and presentation compiler. Choices: (normal,none,discard), default: normal.

Default: normal
Deprecated: Use -Ymacro-expand:none instead.

Don’t expand macros. Might be useful for scaladoc and presentation compiler, but will crash anything which uses macros and gets past typer.


Do not use asynchronous code for repl startup


Use classes to wrap REPL snippets instead of objects

-Yrepl-outdir PATH

Write repl-generated classfiles to given output directory (use “” to generate a temporary dir)


Infer types for arguments of overridden methods.


Do not cache flat classpath representation of classpath elements from jars across compiler instances.


Policy for caching class loaders for compiler plugins that are dynamically loaded. Default: none, help to list choices.

Default: none

Don’t cache class loader


Cache class loader, using file last-modified time to invalidate


Policy for caching class loaders for macros that are dynamically loaded. Default: none, help to list choices.

Default: none

Don’t cache class loader


Cache class loader, using file last-modified time to invalidate


Enable partial unification in type constructor inference


Enable pattern matcher virtualization


Internal only: expose the empty package.


Strategy used for translating lambdas into JVM code. Choices: (inline,method), default: method.

Default: method
-Ybackend-parallelism ARG

maximum worker threads for backend

Default: 1
Min: 1
Max: 16
-Ybackend-worker-queue ARG

backend threads worker queue size

Default: 0
Min: 0
Max: 1000
-Yjar-compression-level ARG

compression level to use when writing jar files

Default: -1
Min: -1
Max: 9

Enable optimizations: _ for all, -opt:help to list choices.

Note: if inline not contained and either l:project or l:classpath are contained, then l:inline is enabled.

Eliminate unreachable code, exception handlers guarding no instructions, redundant metadata (debug information, line numbers).


Simplify branching instructions, eliminate unnecessary ones.


Eliminate empty slots in the sequence of local variables.


Eliminate redundant local variables and unused values (including closures). Enables unreachable-code.


Eliminate redundant casts using a type propagation analysis.


Eliminate box-unbox pairs within the same method (also tuples, xRefs, value class instances). Enables unreachable-code.


Track nullness / non-nullness of local variables and apply optimizations.


Rewrite closure invocations to the implementation method.


Inline method invocations according to -Yopt-inline-heuristics and -opt-inline-from.


Disable optimizations. Takes precedence: -opt:l:none,+box-unbox / -opt:l:none -opt:box-unbox don`t enable box-unbox.


Enable default optimizations: unreachable-code.


Enable intra-method optimizations: unreachable-code,simplify-jumps,compact-locals,copy-propagation,redundant-casts,box-unbox,nullness-tracking,closure-invocations.


Enable cross-method optimizations (note: inlining requires -opt-inline-from): l:method,inline.

Deprecated: Use -opt:l:inline -opt-inline-from instead.

[deprecated, use -opt:l:inline, -opt-inline-from] Enable cross-method optimizations within the current project.

Deprecated: Use -opt:l:inline -opt-inline-from instead.

[deprecated, use -opt:l:inline, -opt-inline-from] Enable cross-method optimizations across the entire classpath.

-opt-inline-from PATTERNS1,PATTERNS2

Patterns for classfile names from which to allow inlining, help for details.


Set the heuristics for inlining decisions. Choices: (at-inline-annotated,everything,default), default: default.

Default: default

Enable optimizer warnings: _ for all, -opt-warnings:help to list choices.


No optimizer warnings.


One-line summary if there were @inline method calls that could not be inlined.


A detailed warning for each @inline method call that could not be inlined.


A detailed warning for every callsite that was chosen for inlining by the heuristics, but could not be inlined.


In mixed compilation, warn at callsites methods defined in java sources (the inlining decision cannot be made without bytecode).


Warn if an inlining decision cannot be made because a the bytecode of a class or member cannot be found on the compilation classpath.


Warn if an inlining decision cannot be made because a Scala classfile does not have a ScalaInlineInfo attribute.


Trace the optimizer progress for methods; _ to print all, prefix match to select.


Print a summary of inliner activity; _ to print all, prefix match to select.

-Ystatistics ARG

Print compiler statistics for specific phases phases (default: parser,typer,patmat,erasure,cleanup,jvm)

Default: parser,typer,patmat,erasure,cleanup,jvm
Note: See Compilation Phases

Enable -Ystatistics to print hot statistics.


Enable profiling.

-Yprofile-destination FILE

where to send profiling output - specify a file, default is to the console.

Note: -Yprofile-enabled is enabled at the same time.
-Yprofile-external-tool ARG

Enable profiling for a phase using an external tool hook. Generally only useful for a single phase phases (default: typer)

Default: typer
Note: -Yprofile-enabled is enabled at the same time.
-Yprofile-run-gc ARG

Run a GC between phases - this allows heap size to be accurate at the expense of more time. Specify a list of phases, or all phases (default: _)

Default: _
Note: -Yprofile-enabled is enabled at the same time.

Trace all scaladoc activity.


Generate, validate and output trees using the interactive compiler.


Print stack traces when a context issues an error.


Trace essential macro-related activities.


Trace all macro-related activities: compilation, generation of synthetics, classloading, expansion, exceptions.


Trace position validation.


Trace reification.


Trace all type assignments.


Trace pattern matching translation.

-Ypatmat-exhaust-depth ARG


Default: 20
Min: 10
Max: 2147483647

Trace quasiquote-related activities.

Warning Settings

This section assembles the -X and -Y options those influence the printing of warnings.


Fail the compilation if there are any warnings.


Enable lint warnings on macro expansions. Default: before, help to list choices.

Default: before

Do not inspect expansions or their original trees when generating unused symbol warnings.


Only inspect unexpanded user-written code for unused symbols.


Only inspect expanded trees when generating unused symbol warnings.


Inspect both user-written code and expanded trees when generating unused symbol warnings.


Warn when dead code is identified.


Warn when non-Unit expression results are unused.

Note: To reduce noises for common idiom, warning are suppressed if type of results are this.type.

Warn when numerics are widened.


Enable or disable specific unused warnings: _ for all, -Ywarn-unused:help to list choices.


Warn if an import selector is not referenced.


Warn if a variable bound in a pattern is unused.


Warn if a private member is unused.


Warn if a local definition is unused.


Warn if an explicit parameter is unused.


Warn if an implicit parameter is unused.


Enable -Ywarn-unused:explicits,implicits.




Warn when more than one implicit parameter section is defined.


Warn when an implicit resolves to an enclosing self-definition.


Enable or disable specific warnings: _ for all, -Xlint:help to list choices.

Note: If this options contains unused, it enables -Ywarn-unused:linted. Otherwise it disables -Ywarn-unused:linted.

Warn if an argument list is modified to match the receiver.

Note: Alias is -Ywarn-adapted-args.

Warn when nullary methods return Unit.

Note: Alias is -Ywarn-nullary-unit.

Warn about inaccessible types in method signatures.

Note: Alias is -Ywarn-inaccessible.

Warn when non-nullary def f() overrides nullary def f.

Note: Alias is -Ywarn-nullary-override.

Warn when a type argument is inferred to be Any.

Note: Alias is -Ywarn-infer-any.

A string literal appears to be missing an interpolator id.


A Scaladoc comment appears to be detached from its element.


A private field (or class parameter) shadows a superclass field.


A local type parameter shadows a type already in scope.


Parameterized overloaded implicit methods are not visible as view bounds.


Option.apply used implicit view.


Selecting member of DelayedInit.


By-name parameter of right associative operator.


Class or object defined in package object.


Pattern match may not be typesafe.


Pattern sequence wildcard must align with sequence component.


Evaluation of a constant arithmetic expression results in an error.


Enable -Ywarn-unused:imports,privates,locals,implicits.

IDE Specific Settings


Print information about presentation compiler tasks.


Enable debugging output for the presentation compiler.


Allow use of the presentation compiler from any thread


Do not report type errors in sources with syntax errors.

-Ypresentation-log FILE

Log presentation compiler events into file

-Ypresentation-replay FILE

Replay presentation compiler events from file

-Ypresentation-delay ARG

Wait number of ms after typing before starting typechecking

Default: 0
Min: 0
Max: 999

Additional resources

Compilation Phases

initializing compiler
parse source files
create symbols
name and type analysis
reference checking
uncurry function types and applications
lambda lifter
represent types as values
add accessors for constructor arguments
make links from inner classes to enclosing one explicit
add explicit constructor for each class
add tail-calls
perform whole program analysis
add one interface per class
expand mixins by code copying
makes boxing explicit
type eraser
generate icode
enable code generation
compilation terminated
matches all phases

Contributors to this page: