What is the caret sign (^) before the dependency version number in Flutter's pubspec.yaml?

Question

In the pubspec.yaml file of my Flutter project there is a caret (^) before the version number of some of the dependencies.

dependencies:   flutter:     sdk: flutter   cupertino_icons: ^0.1.2   english_words: ^3.1.5 

What is its purpose? What does it mean?

Notes

• I looked in the yaml documentation but I didn't see anything that made sense.
• Related: what does Caret sign do in Dart (but it isn't an XOR operator here)
• Related: In Flutter, Dependencies must specify version number? (an answer pointed me in the right direction but the question is asking something different)

Answer 1

The caret sign (^) is used for pub dependencies in Dart to indicate a range of version numbers are allowed. Specifically, any version from the specified version up to (but not including) the next non-breaking version is ok.

• So ^3.1.5 is the same as '>=3.1.5 <4.0.0'
• And ^1.2.3 would be the same as '>=1.2.3 <2.0.0'

It's shorthand for the longer form.

The ^ is saying, I want to automatically use the most up-to-date package from Pub as long as that update won't break anything in my app.

Notes

• The concept of Semantic Versioning is important here. Read the article at the link if you are not familiar with it.
• Version constraints documentation
• Caret syntax documentation

Clarification for versions less than 1.0.0

Originally I had thought that

• ^0.1.2 is the same as '>=0.1.2 <1.0.0' (wrong!)

However, that is an incorrect understanding of Semantic Versioning. When the major version number is 0 (as in the 0 of 0.1.2), the meaning is that the API is unstable and even minor version number changes (as in the 1 of 0.1.2) can indicate a breaking change.

The Semantic Versioning article states:

Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.

and also

How should I deal with revisions in the 0.y.z initial development phase?

The simplest thing to do is start your initial development release at 0.1.0 and then increment the minor version for each subsequent release.

Thus, the following is the corrected form:

• ^0.1.2 is the same as '>=0.1.2 <0.2.0'

Thank you to Günter Zöchbauer for pointing out my error.

See also

• How do Dart Package Versions work & how should I version my Flutter Plugins?