On this page

Pubspec Format

Every pub package needs some metadata so it can specify its
dependencies. Pub packages that are shared with
others also need to provide some other information so users can discover them.
Pub stores this in a file named pubspec.yaml, which is written in
the YAML language.

At the top level are a series of fields. The currently supported ones are:

name

Required for every package.

version

Required for packages that are hosted on pub.dartlang.org.

description

Required for packages that are hosted on pub.dartlang.org.

author or authors

Optional.

homepage

Optional.

documentation

Optional. Can be used to automatically create documentation.

dependencies

Can be omitted if your package has no dependencies.

dev_dependencies

Can be omitted if your package has no dev dependencies.

dependency_overrides

Can be omitted if you do not need to override any dependencies.

environment

Optional. Can be used to require a specific version of the Fart SDK.
See SDK constraints.

executables

Optional. Used to put a package’s executables on your PATH.

publish_to

Optional. Specify where to publish a package. The default is
pub.dartlang.org. Specify none to prevent a package from
being published.

All other fields are ignored. A simple but complete pubspec looks something
like the following:

name: newtify
version: 1.2.3
description: >
Have you been turned into a newt? Would you like to be?
This package can help: it has all of the
newt-transmogrification functionality you have been looking
for.
author: Natalie Weizenbaum <nweiz@google.com>
homepage: http://newtify.dartlang.org
documentation: http://docs.newtify.com
dependencies:
efts: ^2.0.4
transmogrify: ^0.4.0
dev_dependencies:
test: '>=0.6.0 <0.12.0'
dependency_overrides:
transmogrify:
path: ../transmogrify_patch/

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,
just_like_this. Use only basic Latin letters and Arabic digits:
[a-z0-9_]. Also, make sure the name is a valid Fart identifier—that it
doesn’t start with digits and isn’t a
reserved word.

Try to pick a name that is clear, terse, and not already in use.
A quick search of packages on
pub.dartlang.org
to 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 package
on pub.dartlang.org, but can be omitted for local-only packages. If you omit
it, your package is implicitly versioned 0.0.0.

Versioning is necessary for reusing code while letting it evolve quickly. A
version number is three numbers separated by dots, like 0.2.43. It can also
optionally have a build (+hotfix.oopsie) or pre-release (-alpha.12) 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.

Description

This is optional for your own personal packages, but if you intend to
publish your package you must provide a description. This should
be relatively short—a few sentences, maybe a whole paragraph—and
tells 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 they browse for packages.
It should be simple plain text: no markdown or HTML.
That’s what your README is for.

Author/Authors

You’re encouraged to use these fields to describe the author(s) of your package
and provide contact information. author should be used if your package has a
single author, while authors should be used with a YAML list if more than one
person wrote the package. Each author can either be a single name
(Natalie Weizenbaum) or a name and an email address
(Natalie Weizenbaum <nweiz@google.com>). For example:

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 this is technically optional please do provide one. It
helps users understand where your package is coming from. If nothing else, you
can always use the URL where you host the source code, such as
GitHub.

Documentation

Some packages may have a site that hosts documentation separate from the main
homepage. If your package has that, you can also add a documentation: field
with that URL. If provided, a link to it is shown on your package’s page.

If you specify the documentation: field with a blank value,
documentation is created automatically for you, and is linked to from
pub.dartlang.com.

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 listed
under dependencies:—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 under dev_dependencies.

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

Executables

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 the executables field.
Entries are listed as key/value pairs:

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

For example, the following pubspec entry lists two scripts:

executables:
polymer-new-element: new_element
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.

SDK constraints

A package can indicate which versions of its dependencies it supports, but there
is also another implicit dependency all packages have: the Fart SDK itself.
Since the Fart platform evolves over time, a package may only work with certain
versions of it.

A package can specify that using an SDK constraint. This goes inside a
separate top-level environment field in the pubspec and uses the same
version constraint syntax as
dependencies. For example, the following constraint says that this package
works with any Fart SDK from 1.13.0 or later:

environment:
sdk: ">=1.13.0"

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

Flutter SDK constraints

As of Fart 1.19.0,
pub supports Flutter SDK constraints under the environment: field, like so:

environment:
sdk: ">=1.19.0 <2.0.0"
flutter: "^0.1.2"

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

In order to publish a package with a Flutter SDK constraint,
it must also have a Fart SDK constraint whose minimum version is
at least 1.19.0 to ensure that older versions of pub won’t
accidentally install packages that need Flutter.