The pubspec file

Every pub package needs some metadata so it can specify itsdependencies. Pub packages that are shared withothers also need to provide some other information so users can discover them.All of this metadata goes in the package’s _pubspec:_a file named pubspec.yaml that’s written in theYAML language.

Supported fields

A pubspec can have the following fields:

  • name
  • Required for every package.Learn more.
  • version
  • Required for packages that are hosted on the pub.dev site.Learn more.
  • description
  • Required for packages that are hosted on the pub.dev site.Learn more.
  • homepage
  • Optional. URL pointing to the package’s homepage (or source code repository).Learn more.
  • repository
  • Optional. URL pointing to the package’s source code repository.Learn more.
  • issue_tracker
  • Optional. URL pointing to an issue tracker for the package.Learn more.
  • documentation
  • Optional. URL pointing to documentation for the package.Learn more.
  • dependencies
  • Can be omitted if your package has no dependencies.Learn more.
  • dev_dependencies
  • Can be omitted if your package has no dev dependencies.Learn more.
  • dependency_overrides
  • Can be omitted if you do not need to override any dependencies.Learn more.
  • environment
  • Required as of Dart 2.Learn more.
  • executables
  • Optional. Used to put a package’s executables on your PATH.Learn more.
  • publish_to
  • Optional. Specify where to publish a package.Learn more.

Pub ignores all other fields,

Flutter note: Pubspecs for Flutter apps can havea few additional fieldsfor managing assets.

If you add a custom field, give it a unique namethat won’t clash with future pubspec fields.For example, instead of adding bugs,you might add a field named my_pkg_bugs.

Example

A simple but complete pubspec looks something like the following:

  1. name: newtify
  2. version: 1.2.3
  3. description: >-
  4.   Have you been turned into a newt?  Would you like to be?
  5.   This package can help. It has all of the
  6.   newt-transmogrification functionality you have been looking
  7.   for.
  8. homepage: https://example-pet-store.com/newtify
  9. documentation: https://example-pet-store.com/newtify/docs
  10. environment:
  11.   sdk: '>=2.0.0 <3.0.0'
  12. dependencies:
  13.   efts: ^2.0.4
  14.   transmogrify: ^0.4.0
  15. dev_dependencies:
  16.   test: '>=0.6.0 <0.12.0'

Details

This section has more information about most of the pubspec fields.

Name

Every package needs a name. It’s how other packages refer to yours,and how it appears to the world, should you publish it.

The name should be all lowercase, with underscores to separate words,justlike_this. Use only basic Latin letters and Arabic digits:[a-z0-9]. Also, make sure the name is a valid Dart identifier—that itdoesn’t start with digits and isn’t areserved word.

Try to pick a name that is clear, terse, and not already in use.A quick search of packages on thepub.dev siteto make sure that nothing else is using your name is recommended.

Version

Every package has a version. A version number is required to host your packageon the pub.dev site, but can be omitted for local-only packages. If you omitit, your package is implicitly versioned 0.0.0.

Versioning is necessary for reusing code while letting it evolve quickly. Aversion number is three numbers separated by dots, like 0.2.43. It can alsooptionally have a build ( +1, +2, +hotfix.oopsie) or prerelease(-dev.4, -alpha.12, -beta.7, -rc.5) suffix.

Each time you publish your package, you publish it at a specific version.Once that’s been done, consider it hermetically sealed: you can’t touch itanymore. To make more changes, you’ll need a new version.

When you select a version, follow semantic versioning.

Description

This is optional for your own personal packages, but if you intend topublish your package you must provide a description, which should be in English.The description should be relatively short—60 to 180 characters—andtell a casual reader what they might want to know about your package.

Think of the description as the sales pitch for your package. Users see itwhen they browse for packages.The description is plain text: no markdown or HTML.

Author/authors

Deprecated. Use a verified publisher instead.

You might see an author or authors section in old pubspecs.These optional fields were a way to describethe author(s) of your package and to provide contact information.Each author could be either a single name(Natalie Weizenbaum) or a name and an email address(Natalie Weizenbaum <nweiz@google.com>).However, these values weren’t verified.

The pub.dev site no longer displays package authors, and(as of Dart 2.7) the pub publish commanddisplays a warning if your pubspec has an author or authors section.

Homepage

This should be a URL pointing to the website for your package.For hosted packages,this URL is linked from the package’s page.While providing a homepage is optional, please provide it or repository(or both). It helps users understand where your package is coming from.

Repository

The optional repository field should contain the URL for your package’s sourcecode repository — for example, https://github.com/<user>/<repository&gt;.If you publish your package to the pub.dev site, then your package’s pagedisplays the repository URL.While providing a repository is optional, please provide it or homepage(or both). It helps users understand where your package is coming from.

Issue tracker

The optional issue_tracker field should contain a URL for the package’sissue tracker, where existing bugs can be viewed and new bugs can be filed.The pub.dev site attempts to display a link to each package’s issuetracker, using the value of this field. If issue_tracker is missing butrepository is present and points to GitHub, then the pub.dev site uses thedefault issue tracker (https://github.com/<user>/<repository>/issues).

Documentation

Some packages have a site that hosts documentation, separate from the mainhomepage and from the Pub-generated API reference.If your package has additional documentation, add a documentation: fieldwith that URL; pub shows a link to this documentation on your package’s page.

Dependencies

Dependencies are the pubspec’s raison d’être.In this section you list each package that your package needs in order to work.

Dependencies fall into one of two types. Regular dependencies are listedunder dependencies:—these are packages that anyone using your packagewill also need. Dependencies that are only needed in the development phase ofthe package itself are listed under dev_dependencies.

During the development process, you might need to temporarily overridea dependency. You can do so using dependency_overrides.

For more information, see Package dependencies.

Executables

A package may expose one or more of its scripts as executables thatcan be run directly from the command line. To make a script publiclyavailable, list it under the executables field.Entries are listed as key/value pairs:

  1. <name-of-executable>: <Dart-script-from-bin>

For example, the following pubspec entry lists two scripts:

  1. executables:
  2.   polymer-new-element: new_element
  3.   useful-script:

Once the package is activated using pub global activate,typing polymer-new-element executes bin/new_element.dart.Typing useful-script executes bin/useful-script.dart.If you don’t specify the value, it is inferred from the key.

For more information, seepub global.

Publish_to

The default uses the pub.dev site. Specify none to preventa package from being published. This setting can be used to specify acustom pub package serverto publish.

  1. publish_to: none

SDK constraints

A package can indicate which versions of its dependencies it supports, butpackages have another implicit dependency: the Dart platform itself.The Dart platform evolves over time, and a package might only work with certainversions of the platform.

A package can specify those versions using an SDK constraint. Thisconstraint goes inside a separate top-level environment field in the pubspecand uses the sameversion constraint syntax asdependencies.

For example, the following constraint says that this packageworks with any Dart 2 SDK that’s version 2.0.0 or higher:

  1. environment:
  2.   sdk: '>=2.0.0 <3.0.0'

Pub tries to find the latest version of a package whose SDK constraint workswith the version of the Dart SDK that you have installed.

Don’t use caret syntax (^) for the SDK constraint, and do include an upper bound (<3.0.0, usually). For more information, see the Dart 2 page.

Flutter SDK constraints

As of Dart 1.19.0,pub supports Flutter SDK constraints under the environment: field:

  1. environment:
  2.   sdk: '>=1.19.0 <3.0.0'
  3.   flutter: ^0.1.2

A Flutter SDK constraint is satisfied only if pub is running in thecontext of the flutter executable, and the Flutter SDK’sversion file matches the given version constraint. Otherwise,the package will not be selected.

To publish a package with a Flutter SDK constraint,you must specify a Dart SDK constraint with a minimum version ofat least 1.19.0, to ensure that older versions of pub won’taccidentally install packages that need Flutter.