What is Flutter’s pubspec.yaml? Introduction to Its Meaning and Usage!

2024.04.28

This article provides a detailed introduction to the role and usage of pubspec.yaml, which is used for package version management.

What is YAML?

YAML stands for “YAML Ain’t Markup Language” and is a data serialization language designed to represent data concisely. It is used for configuration files like config files and data files like JSON.

YAML uses indentation similar to Python to express hierarchical data.

What is pubspec.yaml in Flutter?

“pubspec.yaml” is a configuration file for Flutter projects that manages the application’s name, description, version information, package dependencies, and the version of those packages.

Structure of pubspec.yaml

The basic structure of “pubspec.yaml” is as follows:

  • “name”:
    　　The name of the application.
  • “description”:
    　　A brief description of the application.
  • “version”:
    　　The version of the application.
  • “environment”:
    　　Specifies the version of the Flutter SDK this project depends on.
  • “dependencies”:
    　　Specifies external packages this project depends on.
  • “dev_dependencies”:
    　　Specifies packages used only during development (such as test frameworks).
    　　Packages like build_runner and riverpod_generator, which are used during development, are defined here.

The actual description is as follows:

name: check
description: A new Flutter project.
version: 1.0.0+1
environment:
  sdk: >=2.17.6 <3.18.2

dependencies:
  cupertino_icons: 1.0.2
  flutter:
    sdk: flutter
  flutter_localizations: 
    sdk: flutter
  flutter_riverpod:

dev_dependencies:
  build_runner: ^2.4.0
  dart_code_metrics: ^5.7.0
  flutter_test:
    sdk: flutter

Meaning of Versions in pubspec.yaml

Package version numbers are represented in the format “major.minor.patch”. The meanings of each number are as follows:

  • “Major”: Increases when there are incompatible major changes.
  • “Minor”: Increases when new features are added without affecting existing functionalities.
  • “Patch”: Increases for bug fixes and small changes.

For example, if specified as [package name: 3.12.4], the major version is 3, the minor version is 12, and the patch version is 4.

Specifying Versions in pubspec.yaml

The versions in pubspec.yaml can be specified as follows:

Package name: [space]
　If no version is specified, the latest version is automatically selected. It is recommended to specify a concrete version for important packages to avoid breaking changes.

Package name: 1.0.0
　The specified version is selected.

Package name: “>=1.0.0 <2.0.0”
　The version is selected within the specified range.

Package name: ^1.0.0
　Automatically selects the version within the range with the same major version as the specified version. This is equivalent to “>=1.0.0 <2.0.0”.

If no version is specified, the latest version is automatically selected, but it is recommended to specify a concrete version for important packages to avoid unexpected issues.

What is pubspec.lock?

The “pubspec.lock” file records the specific versions of each package being used. When a version range is specified, the actual selected version can be checked here.

Version Update Commands

Simply writing in pubspec.yaml does not update the version. Please refer to the following commands:

  • Install: “flutter pub get”
    　Installs the packages listed in pubspec.yaml. If already installed, updates the packages to the latest versions.
  • Upgrade: “flutter pub upgrade”
    　Updates the packages to the latest versions within the specified range.
  • Downgrade: “flutter pub downgrade”
    　Updates the packages to the oldest versions within the specified range.
  • Check Version Dependencies: “flutter pub deps”
    　Displays the version dependency tree and checks the dependencies between packages.
  • Check Version Dependencies: “flutter pub deps”
    　Displays the version dependency tree and checks the dependencies between packages.
  • Check Version: “flutter pub outdated”
    　Check version information for the following:
    　Current: Current version
    　Upgradable: Latest version allowed by pubspec.yaml
    　Resolvable: Latest version available considering other dependencies
    　Latest: Latest version available
  • Major Version Upgrade: flutter pub upgrade –major-versions
    Updates packages listed in pubspec.yaml to the latest versions as much as possible.
  • Individual Update: “flutter pub [command] [package name]
    　After the above command, specifying the package name updates only that package.
    　Example: Install “freezed”: flutter pub get freezed

Conclusion

“pubspec.yaml” mainly serves the role of package management in Flutter projects, but it can also manage project metadata definitions, external package dependencies, and resource specifications.

Version management using pubspec.yaml is crucial for Flutter app development. I often encounter build failures and issues running build_runner due to version management mistakes.

I hope this article helps those struggling with designing pubspec.yaml. Thank you.

Copied title and URL