Flutter pub add and Version Constraints: Avoid Dependency Conflicts

When adding a library to a Flutter project, it is easy to edit pubspec.yaml manually and get the indentation wrong. flutter pub add adds the package and a version constraint to the dependency list, then starts dependency resolution.

pub add updates the declaration and lockfile

pubspec.yaml defines the allowed version range; pubspec.lock records the exact versions selected by resolution. The diagram's 1.2.0 is an example for reading a constraint, not a recommendation for the latest version.

flutter pub add http

After the command, inspect dependencies in pubspec.yaml and the exact resolved versions in pubspec.lock. Application projects commonly commit the lockfile so the team can reproduce installs. Do not infer features, maintenance status, or platform support from the package name alone; check the package's documentation and your project's constraints.

A caret constraint does not allow every future version

dependencies:
  http: ^1.2.0

The 1.2.0 here illustrates syntax, not a current version recommendation. ^1.2.0 allows versions from 1.2.0 up to, but not including, 2.0.0. The upper bound differs for 0.x versions, so do not apply the 1.x rule without checking. A broader range can change what a later resolution selects.

Verify updates with analysis, tests, and builds

After adding or updating a dependency, at least run analysis, tests, and builds for the target platforms. Native plugins can also change Android or iOS configuration. If resolution fails, inspect the conflicting requirements before deleting pubspec.lock.

flutter pub get
flutter analyze
flutter test

If pub get cannot resolve versions, compare direct dependencies in pubspec.yaml with the transitive dependencies named in the error. If analysis passes but one platform build fails, inspect the package's supported platforms and native setup separately. Passing tests does not prove Android or iOS builds succeed.

Distinguish direct from transitive dependencies

When adding a package fails, do not delete the lockfile based only on the two versions shown in an error. Determine whether your project declared a package directly or another dependency brought it in transitively.

flutter pub deps
flutter pub outdated
flutter analyze
flutter test

pub deps shows the resolved dependency graph. pub outdated helps distinguish versions available under current constraints from newer releases. Before widening a constraint, inspect affected direct and transitive dependencies, then rerun analysis, tests, and target-platform builds.

If installation succeeds locally but fails elsewhere, compare pubspec.yaml, pubspec.lock, and the Flutter and Dart SDK versions. Record which constraints conflicted and which resolved versions fixed them; “deleting the lockfile happened to work” is not a reproducible explanation.

Key takeaways

flutter pub add is a practical starting point for declaring and resolving a dependency. Understand the permitted range of a caret constraint, then inspect the lockfile and validate the selected versions with analysis, tests, and platform builds. Also review platform support and licensing when a new package enters the app.