Dart 3.10 is taking off with dot shorthands, stable build hooks, nuanced deprecation annotations, and more!Learn more
Configuring apps with compilation environment declarations
You can specify compilation environment declarations when building or running a Dart application. Compilation environment declarations specify configuration options as key-value pairs that are accessed and evaluated at compile time.
This page uses "environment" to refer to the Dart compilation environment. The common use of the term instead refers to the operating system environment.
Your app can use the values of environment declarations to change its functionality or behavior. Dart compilers can eliminate the code made unreachable due to control flow using the environment declaration values.
You might define and use environment declarations to:
- Add functionality during debugging, such as enabling logging.
- Create separate flavors of your application.
- Configure application behavior, such as the port of an HTTP server.
- Enable an experimental mode of your application for testing.
- Switch between testing and production backends.
To specify an environment declaration when running or compiling a Dart application, use the--define option or its abbreviation,-D. Specify the declaration key-value pair using a<NAME>=<VALUE> format:
$ dart run --define=DEBUG=true -DFLAVOR=freeTo learn how to set these declarations with other tools, check out thespecifying environment declarations section in this guide. That section explains the declaration syntax and how to specify them on the command line and in IDEs and editors.
Accessing environment declarations
# To access specified environment declaration values, use one of thefromEnvironment constructors withconst or within a constant context. Usebool.fromEnvironment fortrue orfalse values,int.fromEnvironment for integer values, andString.fromEnvironment for anything else.
The environment declaration constructors are only guaranteed to work when invoked asconst. Most compilers must be able to evaluate their value at compile time.
Each of thefromEnvironment constructors require the name or key of the environment declaration. They also accept an optionaldefaultValue named argument to override the default fallback value. The default fallback value is used when a declaration isn't defined or the specified value cannot be parsed as the expected type.
For example, if you want to print log messages only when the environment declarationDEBUG is set totrue:
voidlog(Stringmessage){// Log the debug message if the environment declaration 'DEBUG' is `true`.// If there was no value specified, do not log.if(constbool.fromEnvironment('DEBUG',defaultValue:false)){print('Debug:$message');}} In this snippet, ifDEBUG is set tofalse during compilation, or not specified at all, production compilers can completely remove the condition and its body.
ThefromEnvironment constructors fallback to a default value when the declaration isn't specified or the specified value cannot be parsed. Therefore, to specifically check whether an environment declaration has been specified, use thebool.hasEnvironment constructor:
if(constbool.hasEnvironment('DEBUG')){print('Debug behavior was configured!');}Specifying environment declarations
#Dart tools and compilers currently do not consistently handle environment declarations with comma-separated values. To track standardization of this handling, referenceSDK issue 44995.
Dart CLI
# Bothdart run and thedart compile subcommands accept any number of the-D or--define options to specify environment declaration values.
$ dart run --define=DEBUG=true -DFLAVOR=free main.dart$ dart compile exe --define=DEBUG=true -DFLAVOR=free main.dart$ dart compile js --define=DEBUG=true -DFLAVOR=free main.dart$ dart compile aot-snapshot --define=DEBUG=true -DFLAVOR=free main.dart$ dart compile jit-snapshot --define=DEBUG=true -DFLAVOR=free main.dart$ dart compile kernel --define=DEBUG=true -DFLAVOR=free main.dartwebdev
# To learn about configuringwebdev to pass environment declarations to both the development and production web compilers, check outthewebdev configuration documentation.
Visual Studio Code
# In your launch configuration (launch.json) underconfigurations, add a newtoolArgs key containing your desired environment declarations:
"configurations":[{"name":"Dart","request":"launch","type":"dart","toolArgs":["--define=DEBUG=true"]}]To learn more, check out the documentation forVS Code launch configurations.
JetBrains IDEs
#In theRun/Debug Configurations for your project, add your desired environment declarations toVM options:
To learn more, check out JetBrains' documentation forDart Run/Debug Configurations.
Flutter
# To specify environment declarations to the Flutter tool, use the--dart-define option instead:
$ flutter run --dart-define=DEBUG=trueUnless stated otherwise, the documentation on this site reflects Dart 3.10.0. Page last updated on 2025-8-7.View source orreport an issue.