Flutter pubspec options

Every project written in the Dart language, including all Flutter apps and libraries, includes a pubspec.yaml file, referred to as the pubspec. Creating a new project generates a basic pubspec at the top of the project tree that contains metadata and lists project dependencies.

Fields common to both Dart and Flutter projects are described in The pubspec file on dart.dev. This page lists fields that are only valid for a Flutter project.

When you create a new project with the flutter create command (or by using the equivalent button in your IDE), it creates a pubspec for a basic Flutter app.

The first time you build your project, it also creates a pubspec.lock file that contains specific versions of the included packages. This ensures that you get the same version the next time the project is built. To learn more about how Flutter and Dart resolve package dependencies, check out Package dependency management.

The following example of a pubspec file highlights fields used only in a Flutter app. Learn more about the non-highlighted fields on dart.dev.

name: <project name>
description: A new Flutter project.
​
publish_to: 'none'  # Remove this line if you wish to publish to pub.dev
version: 1.0.0+1
​
environment:
  sdk: ^3.13.0
​
dependencies:
  flutter:       # Required for every Flutter project
    sdk: flutter # Required for every Flutter project
  flutter_localizations: # Required to enable localization
    sdk: flutter         # Required to enable localization
​
  cupertino_icons: ^1.0.8 # Only required if you use Cupertino (iOS style) icons
​
dev_dependencies:
  flutter_test:
    sdk: flutter # Required for a Flutter project that includes tests
  integration_test:
    sdk: flutter # Required for integration tests
​
  flutter_lints: ^6.0.0 # Contains a set of recommended lints for Flutter code
​
flutter:
​
  uses-material-design: true # Required if you use the Material icon font
​
  generate: true # Enables generation of localized strings from arb files
​
  config: # App-specific configuration flags that mirror `flutter config`
    enable-swift-package-manager: true
​
  assets:  # Lists assets, such as image files
    - images/a_dot_burr.jpeg
    - images/a_dot_ham.jpeg
​
  licenses: # Lists additional license files to be bundled with the app
    - assets/my_license.txt
​
  fonts:              # Required if your app uses custom fonts
    - family: Schyler
      fonts:
        - asset: fonts/Schyler-Regular.ttf
        - asset: fonts/Schyler-Italic.ttf
          style: italic
    - family: Trajan Pro
      fonts:
        - asset: fonts/TrajanPro.ttf
        - asset: fonts/TrajanPro_Bold.ttf
          weight: 700

This page discusses Flutter-only pubspec fields. Learn more about general Dart fields in Dart's pubspec supported fields.

A list of asset paths that your app uses. These assets are bundled with your application. Common types of assets include static data (for example, JSON), configuration files, icons, and images (JPEG, WebP, GIF, animated WebP/GIF, PNG, BMP, and WBMP).

Besides listing the images that are included in the app package, an image asset can also refer to one or more resolution-specific "variants". For more information, visit the resolution aware section of the Assets and images page. For information on adding assets from package dependencies, visit the asset images in package dependencies section in the same page.

The assets field has the following structure:

flutter:
  assets:
    - [ path_to_file | path_to_directory ]
      [ flavor_path_field | platform_path_field | transformer_path_field ]
    [...]

# path_to_file structure
- path/to/directory/file

# path_to_directory structure
- path/to/directory/

# flavor_path_field structure
- path: path/to/directory
  flavors:
    - flavor_name

# platform_path_field structure
- path: path/to/file
  platforms:
    - platform_name

# transformer_path_field structure
- path: path/to/file
  transformers:
    - package: transformer_package_name
      args: ['arg1', 'arg2'] # Optional

Subfields of assets:

• path_to_file: A string that represents the path to a file.
• path_to_directory: A string that represents the path to a directory.
• flavor_path_field: A path field and its flavor subfields.
• platform_path_field: A path field and its platform subfields.
• transformer_path_field: A path field and its transformer subfields.
• path: The path to an asset file or directory.
• flavors: A list of flutter flavors to use with assets at a specific path. To learn more about flavors, visit Set up flavors for iOS and macOS and Set up flavors for Android.
• platforms: A list of platforms to use with assets at a specific path. Valid values are android, ios, web, linux, macos, and windows.
• transformers: A list of transformer packages to run on the asset at build time. To learn more, see Transforming assets at build time.

You can pass in a path to a file:

flutter:
  assets:
    - assets/images/my_image_a.png
    - assets/images/my_image_b.png

You can pass in a path to a directory:

flutter:
  assets:
    - assets/images/
    - assets/icons/

You can pass in a path to a directory for specific flavors:

flutter:
  assets:
    - path: assets/flavor_a_and_b/images
      flavors:
        - flavor_a
        - flavor_b
    - path: assets/flavor_c/images
      flavors:
        - flavor_c

You can pass in a path to a file for specific platforms:

flutter:
  assets:
    - path: assets/web_worker.js
      platforms:
        - web
    - path: assets/desktop_icon.png
      platforms:
        - windows
        - linux
        - macos

You can configure build-time asset transformers:

flutter:
  assets:
    - path: assets/logo.svg
      transformers:
        - package: vector_graphics_compiler
          args: ['--tessellate']

A map of keys to flags (true or false) that influences how the flutter CLI is executed.

The available keys mirror those available in flutter config --list.

flutter:
  config:
    cli-animations: false

Use flutter config --help for a description of each flag.

Flags are only read from the current application package, and have no effect in the context of a package or dependency.

Control whether Flutter uses Swift Package Manager to manage native iOS and macOS dependencies for this project. To disable it for this project, set the field to false.

flutter:
  config:
    enable-swift-package-manager: false

Assign a default Flutter flavor for an app. When used, you don't need to include the name of this flavor in the Flutter launch command.

flutter:
  default-flavor: flavor_name

In the following example, an Android Flutter app has a flavor called staging and production. The production flavor is the default flavor. When that flavor is run, you don't need to include it in the launch command.

flutter:
  default-flavor: production

# Use this command to run the default flavor (production).
$ flutter run

# Use this command to run non-default flavors (staging).
$ flutter run --flavor staging

To learn how to create Flutter flavors, visit Set up Flutter flavors for Android and Set up Flutter flavors for iOS and macOS.

Defer downloading components to reduce the initial download size of an Android app. Most often used with large applications, modularized applications, and applications with on-demand features.

The deferred-components field has the following structure:

flutter:
  deferred-components:
    - name: component_name
      libraries:
        - string_expression
        [...]
      assets:
        - string_expression
        [...]
    [...]

Deferred component subfields:

• name: The unique identifier for a specific deferred component.
• libraries: A list of Dart libraries that are part of the deferred component.
• assets: A list of asset paths that are associated with the deferred component.

Example:

flutter:
  deferred-components:
    - name: box_component
      libraries:
        - package:testdeferredcomponents/box.dart
    - name: gallery_feature
      libraries:
        - package:testdeferredcomponents/gallery_feature.dart
      assets:
        - assets/gallery_images/gallery_feature.png

To learn more about how you can use deferred components with a Flutter Android app, see Deferred components for Android.

A field that contains Flutter-specific settings for your app.

flutter:
  [flutter_field]
  [...]

Configure and include custom fonts in your Flutter application.

For examples of using fonts visit the Use a custom font and Export fonts from a package recipes in the Flutter cookbook.

The fonts field has the following structure:

flutter:
  fonts:
    -  { font_family_field | font_asset_field }
    [...]

# font_family_field structure
- family: font_name
  fonts:
    - font_asset_field
    [...]

# font_asset_field structure
- asset: path/to/directory/font_name
  weight: int_expression # Optional
  style: string_expression # Optional

Subfields of fonts:

• family: Optional. The font family name. Can have multiple font assets.
• asset: The font to use.
• weight: Optional. The weight of the font. This can be 100, 200, 300, 400, 500, 600, 700, 800 or 900.
• style: Optional. The style of the font. This can be italic.

Use a font that is not part of a font family:

flutter:
  fonts:
    - asset: fonts/Roboto-Regular.ttf
      weight: 900 # Optional
      style: italic # Optional

Use a font family:

flutter:
  fonts:
    - family: Roboto # Optional
      fonts:
        - asset: fonts/Roboto-Regular.ttf
        - asset: fonts/Roboto-Bold.ttf
          weight: 700 # Optional
          style: italic # Optional

Alternatively, if you have a font that requires no family, weight or style requirements, you can declare it as a simple asset:

flutter:
  assets:
    - fonts/Roboto-Regular.ttf

Enables generation of Dart files with localized strings from .arb files.

Enable general localization:

flutter:
  generate: true

To learn more, visit Internationalizing Flutter apps.

A list of additional license file paths that should be bundled with your application. These files are typically found within your project's assets directory.

The licenses field has the following structure:

flutter:
  licenses:
    - [path_to_file]

Configure settings for a Flutter module project when adding Flutter to an existing host Android or iOS application (Add-to-App).

The module field has the following structure:

flutter:
  module:
    androidPackage: com.example.my_module # Optional
    iosBundleIdentifier: com.example.myModule # Optional

Subfields of module:

• androidX: Optional. Specifies whether the module uses AndroidX.
• androidPackage: Optional. The package name used for generated Android code.
• iosBundleIdentifier: Optional. The bundle identifier used for generated iOS code.

To learn more, visit Add Flutter to existing apps.

Configure settings specifically for Flutter plugins.

The plugin field has the following structure:

flutter:
  plugin:
    platforms:
      android: # Optional
        package: com.example.my_plugin
        pluginClass: MyPlugin
        dartPluginClass: MyPluginClassName
        ffiPlugin: true
        default_package: my_plugin_name
        fileName: my_file.dart
      ios: # Optional
        pluginClass: MyPlugin
        dartPluginClass: MyPluginClassName
        ffiPlugin: true
        default_package: my_plugin_name
        fileName: my_file.dart
        sharedDarwinSource: true
      macos: # Optional
        pluginClass: MyPlugin
        dartPluginClass: MyPluginClassName
        ffiPlugin: true
        default_package: my_plugin_name
        fileName: my_file.dart
        sharedDarwinSource: true
      windows: # Optional
        pluginClass: MyPlugin
        dartPluginClass: MyPluginClassName
        ffiPlugin: true
        default_package: my_plugin_name
        fileName: my_file.dart
      linux: # Optional
        pluginClass: MyPlugin
        dartPluginClass: MyPluginClassName
        ffiPlugin: true
        default_package: my_plugin_name
        fileName: my_file.dart
      web: # Optional
        ffiPlugin: true
        default_package: my_plugin_name
        fileName: my_file.dart
    implements: # Optional
      - example_platform_interface

Subfields of plugin:

• platforms: A list of platforms that will have configuration settings.
• package: The Android package name of the plugin. This can be used with the Android platform and is required.
• pluginClass: The name of the plugin class. Optional if dartPluginClass is used for the same platform. This can be used with the Android, iOS, Linux macOS, and Windows platforms.
• default_package: Optional. The package that should be used as the default implementation of a platform interface. Only applicable to federated plugins, where the plugin's implementation is split into multiple platform-specific packages.
• dartPluginClass: Optional. The Dart class that serves as the entry point for a Flutter plugin. This can be used with the Android, iOS, Linux macOS, and Windows platforms.
• sharedDarwinSource: Optional. Indicates that the plugin shares native code between iOS and macOS. This can be used with the iOS and macOS platforms.
• fileName: Optional. The file that contains the plugin class.
• ffiPlugin: Optional. True if the plugin uses a Foreign Function Interface (FFI).
• implements: Optional. The platform interfaces that a Flutter plugin implements.

To learn more about plugins, see Developing packages & plugins.

GLSL Shaders with the .frag extension must be declared in the shaders section of your project's pubspec.yaml file. The Flutter command-line tool compiles the shader to its appropriate backend format and generates its necessary runtime metadata. The compiled shader is then included in the application just like an asset.

The shaders field has the following structure:

flutter:
  shaders:
    -  { path_to_file | path_to_directory }
    [...]

# path_to_file structure
- assets/shaders/file

# path_to_directory structure
- assets/shaders/

Add specific shaders:

flutter:
  shaders:
    - assets/shaders/shader_a.frag
    - assets/shaders/shader_b.frag

Add a directory of shaders:

flutter:
  shaders:
    - assets/shaders/

Alternatively, you can add your shader directory to the assets field:

flutter:
  assets:
    - assets/shaders/my_shader.frag

Like other assets, shaders also support flavors and transformers.

Use Material Design components and icon font in your Flutter app.

flutter:
  uses-material-design: true

The following Flutter-specific packages can be added to the pubspec. If you add a package, run flutter pub get in your terminal to install the package.

A package that represents the Flutter SDK itself and can be added to the dependencies field. Use this if your project relies on the Flutter SDK, not a regular package from pub.dev.

dependencies:
  flutter:
    sdk: flutter

A package provided by the Flutter SDK that enables localization of ARB files. Often used with the intl package.

dependencies:
  flutter_localizations:
    sdk: flutter
  intl: any

A package provided by the Flutter SDK that contains testing utilities for unit and widget tests for your Flutter app.

dev_dependencies:
  flutter_test:
    sdk: flutter

A package provided by the Flutter SDK for running integration tests on target devices or emulators.

dev_dependencies:
  integration_test:
    sdk: flutter

To learn more, visit Integration testing.

A package that provides a set of recommended lints for Flutter projects. This package can be added to the dev_dependencies field in the pubspec.

dev_dependencies:
  flutter_lints: ^6.0.0

A package that provides a set of Apple's Cupertino icons for use in Flutter applications. This package can be added to the dependencies field in the pubspec.

dependencies:
  cupertino_icons: ^1.0.8

For more information on packages, plugins, and pubspec files, visit the following:

• Add Flutter to existing apps
• Creating packages on dart.dev
• Glossary of package terms on dart.dev
• Integration testing
• Package dependency management
• Package dependencies on dart.dev
• Set up Flutter flavors for Android
• Set up Flutter flavors for iOS and macOS
• Transforming assets at build time
• Using packages
• What not to commit on dart.dev