Everypub package needs some metadata so it can specify itsdependenciesDependencyA Dart package that a package relies on.Learn more. Pub packages that are shared with others also need to provide some other information so users can discover them. All of this metadata goes in the package'spubspec: a file namedpubspec.yaml that's written in theYAML language.

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.

platforms

Optional. Used to explicitly declare supported platforms on the pub.dev site.Learn more.

publish_to

Optional. Specify where to publish a package.Learn more.

funding

Optional. List of URLs where users can sponsor development of the package.Learn more.

false_secrets

Optional. Specify files to ignore when conducting a pre-publishing search for potential leaks of secrets.Learn more.

screenshots

Optional. Specify a list of screenshot files to display on thepub.dev site.Learn more.

topics

Optional. List of topics for the package.Learn more.

ignored_advisories

Optional. List of ignored security advisories.Learn more.

Pub ignores all other fields.

If you add a custom field, give it a unique name that won't clash with future pubspec fields. For example, instead of addingbugs, you might add a field namedmy_pkg_bugs.

A simple but complete pubspec looks something like the following:

name:newtifydescription:>-Have you been turned into a newt?  Would you like to be?This package can help. It has all of thenewt-transmogrification functionality you have been lookingfor.version:1.2.3homepage:https://example-pet-store.com/newtifydocumentation:https://example-pet-store.com/newtify/docs​environment:sdk:'^3.2.0'​dependencies:efts:^2.0.4transmogrify:^0.4.0​dev_dependencies:test:'>=1.15.0 <2.0.0'

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

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,just_like_this. Use only basic Latin letters and Arabic digits:[a-z0-9_]. Also, make sure the name is a valid Dart identifier—that it doesn'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 site to make sure that nothing else is using your name is recommended.

Every package has a version. A version number is required to host your package on the pub.dev site, but can be omitted for local-only packages. If you omit it, your package is implicitly versioned0.0.0.

Versioning is necessary for reusing code while letting it evolve quickly. A version number is three numbers separated by dots, like0.2.43. It can also optionally 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 it anymore. To make more changes, you'll need a new version.

When you select a version, followsemantic versioning.

This is optional for your own personal packages, but if you intend to publish your package you must provide a description, which should be in English. The description should be relatively short—60 to 180 characters—and tell 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 it when theybrowse for packages. The description is plain text: no markdown or HTML.

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

The optionalrepository field should contain the URL for your package's source code repository—for example,https://github.com/<user>/<repository>. If you publish your package to the pub.dev site, then your package's page displays the repository URL. While providing arepository is optional,please provide it orhomepage (or both). It helps users understand where your package is coming from.

The optionalissue_tracker field should contain a URL for the package's issue 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 issue tracker, using the value of this field. Ifissue_tracker is missing butrepository is present and points to GitHub, then the pub.dev site uses the default issue tracker (https://github.com/<user>/<repository>/issues).

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

DependenciesDependencyA Dart package that a package relies on.Learn more are the pubspec'sraison 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 listed underdependencies:—these are packages that anyone using your package will also need. Dependencies that are only needed in the development phase of the package itself are listed underdev_dependencies.

During the development process, you might need to temporarily override a dependency. You can do so usingdependency_overrides.

For more information, seePackage dependencies.

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

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

For example, the following pubspec entry lists two scripts:

executables:slidy:mainfvm:

Once the package is activated usingdart pub global activate, typingslidy executesbin/main.dart. Typingfvm executesbin/fvm.dart. If you don't specify the value, it is inferred from the key.

For more information, seepub global.

When youpublish a package, pub.dev automatically detects the platforms that the package supports. If this platform-support list is incorrect, useplatforms to explicitly declare which platforms your package supports.

For example, the followingplatforms entry causes pub.dev to list the package as supporting Android, iOS, Linux, macOS, Web, and Windows:

# This package supports all platforms listed below.platforms:android:ios:linux:macos:web:windows:

Here is an example of declaring that the package supports only Linux and macOS (and not, for example, Windows):

# This package supports only Linux and macOS.platforms:linux:macos:

The default uses thepub.dev site. Specifynone to prevent a package from being published. This setting can be used to specify acustom pub package server to publish.

publish_to:none

Package authors can use thefunding property to specify a list of URLs that provide information on how users can help fund the development of the package. For example:

funding:-https://www.buymeacoffee.com/example_user-https://www.patreon.com/some-account

If published topub.dev the links are displayed on the package page. This aims to help users fund the development of their dependencies.

When you try topublish a package, pub conducts a search for potential leaks of secret credentials, API keys, or cryptographic keys. If pub detects a potential leak in a file that would be published, then pub warns you and refuses to publish the package.

Leak detection isn't perfect. To avoid false positives, you can tell pub not to search for leaks in certain files, by creating an allowlist usinggitignore patterns underfalse_secrets in the pubspec.

For example, the following entry causes pub not to look for leaks in the filelib/src/hardcoded_api_key.dart and in all.pem files in thetest/localhost_certificates/ directory:

false_secrets:-/lib/src/hardcoded_api_key.dart-/test/localhost_certificates/*.pem

Starting agitignore pattern with slash (/) ensures that the pattern is considered relative to the package's root directory.

Packages can showcase their widgets or other visual elements using screenshots displayed on their pub.dev page. To specify screenshots for the package to display, use thescreenshots field.

A package can list up to 10 screenshots under thescreenshots field. Don't include logos or other branding imagery in this section. Each screenshot includes onedescription and onepath. Thedescription explains what the screenshot depicts in no more than 160 characters. For example:

screenshots:-description:'This screenshot shows the transformation of a number of bytes  to a human-readable expression.'path:path/to/image/in/package/500x500.webp-description:'This screenshot shows a stack trace returning a human-readable  representation.'path:path/to/image/in/package.png

Pub.dev limits screenshots to the following specifications:

• File size: max 4 MB per image.
• File types:png,jpg,gif, orwebp.
• Static and animated images are both allowed.

Keep screenshot files small. Each download of the package includes all screenshot files.

Pub.dev generates the package's thumbnail image from the first screenshot. If this screenshot uses animation, pub.dev uses its first frame.

Package authors can use thetopics field to categorize their package. Topics can be used to assist discoverability during search with filters on pub.dev. Pub.dev displays the topics on the package page as well as in the search results.

The field consists of a list of names. For example:

topics:-network-http

Pub.dev requires topics to follow these specifications:

• Tag each package with at most 5 topics.
• Write the topic name following these requirements:
  • Use between 2 and 32 characters.
  • Use only lowercase alphanumeric characters or hyphens (a-z,0-9,-).
  • Don't use two consecutive hyphens (--).
  • Start the name with lowercase alphabet characters (a-z).
  • End with alphanumeric characters (a-z or0-9).

When choosing topics, consider ifexisting topics are relevant. Tagging with existing topics helps users discover your package.

If a package has a dependency that is affected by a security advisory, pub warns about the advisory during dependency resolution. Package authors can use theignored_advisories field as an allowlist of triggered advisories that are not relevant for the package.

To suppress the warning about an advisory, add the advisory identifier to theignored_advisories list. For example:

name:myappdependencies:foo:^1.0.0ignored_advisories:-GHSA-4rgh-jx4f-qfcq

For more information, check outSecurity advisories.

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

A package can specify those versions using anSDK constraint. This constraint goes inside a separate top-levelenvironment field in the pubspec and uses the sameversion constraint syntax as dependencies.

For example, the following constraint says that this package works with any Dart SDK that's version 3.0.0 or higher:

environment:sdk:^3.0.0

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

Omitting the SDK constraint is an error. When the pubspec has no SDK constraint,dart pub get fails with a message like the following:

pubspec.yaml has no lower-bound SDK constraint.You should edit pubspec.yaml to contain an SDK constraint:environment:  sdk: '^3.2.0'See https://dart.dev/go/sdk-constraint

Pub supports specifying Flutter SDK constraints under theenvironment: field:

environment:sdk:^3.2.0flutter:'>=3.22.0'

A Flutter SDK constraint is satisfied only if pub is running in the context of theflutter executable, and the Flutter SDK'sversion file meets the version constraint's lower bound. Otherwise, the package won't be selected.

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