pubspec.yaml — What It Is, Structure and Dependency Configuration in Flutter

What Is pubspec.yaml

pubspec.yaml is a manifest file in YAML format that the pub package manager uses to manage Dart and Flutter projects. It is located in the project root and is processed with every flutter pub get command. Unlike other platforms where configuration is spread across multiple files, Flutter uses a single centralized manifest for all needs.

The file contains metadata: project name, description, version, author. This data is used when publishing a package to pub.dev and when building the application for App Store and Google Play. The description field is displayed in the package search results, so it should be informative and contain keywords that other developers can use to find the library.

Without a correct pubspec.yaml, a Flutter project cannot be built. Syntax errors or incorrect indentation lead to an immediate compilation failure with an Error on line X message. YAML is sensitive to whitespace: one extra space changes the data structure, and tabs cause a syntax error. Therefore, when editing pubspec.yaml manually, it is important to use an editor with YAML syntax highlighting, such as VS Code with the official Flutter extension.

Main Sections of pubspec.yaml

pubspec.yaml consists of required and optional sections. Each section is responsible for a specific aspect of the project’s configuration. The order of sections does not matter, but by community convention the hierarchy is: metadata, environment, dependencies, resources, platforms.

name and description

The name field sets a unique package identifier in snake_case format, consisting only of lowercase Latin letters, digits, and underscores. The description field is a brief project summary of up to 180 characters, required for publishing on pub.dev. The description should explain the package’s purpose without repeating the name, and contain keywords for repository search optimization.

name: my_flutter_app
description: Task management app with Flutter
publish_to: 'none'

version and environment

The version field uses semantic versioning major.minor.patch with an optional build number after the plus sign (1.0.0+1). The environment section sets the minimum and maximum versions of the Dart and Flutter SDK to ensure compatibility. If a new SDK version contains breaking changes incompatible with the project code, the build will abort with a clear error message.

version: 1.0.0+1
environment:
  sdk: '>=3.2.0 <4.0.0'
  flutter: '>=3.16.0'

dependencies and dev_dependencies

The dependencies section lists packages required for the application to run at runtime. The dev_dependencies section contains packages for testing, code generation, and development — they are not included in the release build. Separating dependencies is critical for performance: each package in dependencies increases the final APK or IPA size, as well as the application startup time due to the initialization of additional libraries.

dependencies:
  flutter:
    sdk: flutter
  http: ^1.2.0
  provider: ^6.1.0
  shared_preferences: ^2.2.0
  cached_network_image: ^3.3.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  mockito: ^5.4.0
  build_runner: ^2.4.0

Configuring Assets and Fonts

The flutter section contains subsections for configuring resources, fonts, and platform parameters. Resources are connected via a paths array specifying specific files or entire directories. All paths are specified relative to the project root, not relative to pubspec.yaml. This is an important nuance that often causes confusion for beginner Flutter developers.

flutter:
  uses-material-design: true
  assets:
    - assets/images/
    - assets/icons/
    - assets/config.json
    - assets/data/translations/
  fonts:
    - family: RobotoMono
      fonts:
        - asset: fonts/RobotoMono-Regular.ttf
        - asset: fonts/RobotoMono-Bold.ttf
          weight: 700
        - asset: fonts/RobotoMono-Italic.ttf
          style: italic

Connecting assets through pubspec.yaml makes files accessible via AssetBundle at runtime. This works for images, JSON, text files, and any other resources. Flutter automatically supports different screen resolutions: if you add images/2x/ and images/3x/, Flutter will select the appropriate image version based on the device pixel ratio. To do this, simply specify only the root images/ folder in assets.

Custom fonts are added through the fonts section with a family name and a list of styles. After modifying pubspec.yaml, you need to run flutter pub get to apply the changes. Fonts can be used both globally in the MaterialApp theme and locally in specific widgets. For each style, you can specify weight (100–900) and style (normal, italic), which allows Flutter to correctly select the font file when using FontWeight and FontStyle in code.

Dependency and Version Management

pub supports several ways to specify sources for dependencies: pub.dev, Git repositories, local paths, and private repositories. The choice of source depends on the development stage: pub.dev is used for stable versions, Git for forks and custom modifications, and local paths for libraries being developed in parallel.

The ^version operator means a compatible version: ^1.2.0 allows versions >=1.2.0 and <2.0.0. This is analogous to the ~> operator in CocoaPods and the Caret operator in npm. pub automatically resolves Dependency Hell using a SAT solver algorithm that finds a combination of versions satisfying all constraints. If such a combination does not exist, pub outputs a detailed message indicating the conflicting packages.

The pubspec.lock file locks exact dependency versions. It should be stored in version control for applications to ensure reproducible builds on all team machines. For libraries, pubspec.lock is not included in the repository because library users should be able to use it with different dependency versions. The flutter pub upgrade command updates all dependencies according to pubspec.yaml constraints, while flutter pub outdated shows which packages can be updated.

Build and Publishing Configuration

To publish an application on pub.dev, settings are specified in the publish_to section. The value 'none' prevents accidental package publishing, which is important for internal or non-public projects. If publish_to is missing, pub attempts to publish the package to the default pub.dev, which could lead to unwanted code leaks.

The flutter section includes platform parameters: generate for automatic generation of platform files, and deferred-components for modular functionality loading. The generate: true parameter forces Flutter to automatically create and update platform projects (iOS, Android, Web) when adding new platforms via flutter create --platforms. Without this parameter, the platform folder structure may become out of sync with pubspec.yaml.

flutter:
  generate: true
  deferred-components:
    - name: photoEditor
      libraries:
        - package:photo_editor/library.dart

The platforms section sets the target platforms for the package. For applications, it is automatically determined when adding support for a specific platform via flutter create. Platforms can be added and removed manually by editing pubspec.yaml. Deferred Components allow loading parts of the application on demand, reducing the install size — this is especially relevant for games and applications with a large amount of rarely used content.

When publishing a package, pub checks all pubspec.yaml fields for compliance with the repository’s requirements. Missing required fields name, version, and description lead to publication rejection. Additionally, the correctness of the license, the presence of README.md and CHANGELOG.md are checked. Packages with code analyzer errors (dart analyze) also fail validation. After successful publication, the package becomes available on pub.dev within a few minutes.

The dependency_overrides section allows you to force a specific package version, ignoring constraints from transitive dependencies. This is a powerful but dangerous mechanism: if used incorrectly, it can lead to library incompatibilities. Use dependency_overrides only temporarily to resolve conflicts or test new versions. After fixing the main dependencies, the override should be removed to avoid breaking the project’s dependency graph in the long term.

The executables section in pubspec.yaml allows specifying executable scripts that pub installs in PATH when activating a package. This is useful for CLI tools written in Dart, such as build_runner or dart_code_metrics. The dart pub global activate command installs the package globally, making the scripts specified in executables accessible from the terminal. For applications, executables are usually not used, as the entry point is defined through main in lib/main.dart.