Contents

Sound null safety

The Dart language comes with sound null safety.

Null safety prevents errors that result from unintentional access of variables set to null. For example, if a method expects an integer but receives null, your app causes a runtime error. This type of error, a null dereference error, can be difficult to debug.

With sound null safety variables are ‘non-nullable’ by default: They can be assigned only values of the declared type (e.g. int i=42), and never be assigned null. You can specify that a type of a variable is nullable (e.g. int? i), and only then can they contain either a null or a value of the defined type.

Sound null safety changes potential runtime errors into edit-time analysis errors, by flagging when any non-nullable variable hasn’t been initialized with a non-null value or is being assigned a null. This allows you to fix these errors before deploying your app.

Introduction through examples

With null safety, all of the variables in the following code are non-nullable:

// In null-safe Dart, none of these can ever be null.
var i = 42; // Inferred to be an int.
String name = getFileName();
final b = Foo();

To indicate that a variable might have the value null, just add ? to its type declaration:

int? aNullableInt = null;

Null safety principles

Dart null safety support is based on the following three core design principles:

  • Non-nullable by default. Unless you explicitly tell Dart that a variable can be null, it’s considered non-nullable. This default was chosen after research found that non-null was by far the most common choice in APIs.

  • Incrementally adoptable. You choose what to migrate to null safety, and when. You can migrate incrementally, mixing null-safe and non-null-safe code in the same project. We provide tools to help you with the migration.

  • Fully sound. Dart’s null safety is sound, which enables compiler optimizations. If the type system determines that something isn’t null, then that thing can never be null. Once you migrate your whole project and its dependencies to null safety, you reap the full benefits of soundness—not only fewer bugs, but smaller binaries and faster execution.

Enabling/disabling null safety

You can use sound null safety in Dart 2.12 and Flutter 2.0 or later. Dart 3 and later will only support sound null safety.

To enable sound null safety, set the SDK constraint lower-bound to a language version of 2.12 or later. For example, your pubspec.yaml file might have the following constraints:

environment:
  sdk: '>=2.12.0 <3.0.0'

Migrating an existing package or app

The Dart SDK includes the dart migrate tool. This tool helps you migrate code that supports sound null safety. Use dart migrate if you wrote Dart code with Dart 2.12 or earlier.

$ cd my_app
$ dart migrate

To learn how to migrate your code to null safety, see the migration guide.

Where to learn more

For more information about null safety, see the following resources: