How to use packages

Most Dart-savvy IDEs offer support for using pub that includes creating, downloading, updating, and publishing packages. Or you can use .

At a minimum, a Dart package is a directory containing a pubspec file. The pubspec contains some metadata about the package. Additionally, a package can contain dependencies (listed in the pubspec), Dart libraries, apps, resources, tests, images, and examples.

To use a package, do the following:

Create a pubspec (a file named pubspec.yaml that lists package dependencies and includes other metadata, such as a version number).
Use pub to get your package’s dependencies.
If your Dart code depends on a library in the package, import the library.

The pubspec is a file named pubspec.yaml that’s in the top directory of your application. The simplest possible pubspec lists only the package name:

Here is an example of a pubspec that declares dependencies on two packages (js and intl) that are hosted on the pub.dev site:

dependencies:
  js: ^0.6.0
  intl: ^0.15.8

For details on creating a pubspec, see the and the documentation for the packages that you want to use.

Once you have a pubspec, you can run pub get from the top directory of your application:

The pub get command determines which packages your app depends on, and puts them in a central . If your app depends on a published package, pub downloads that package from the pub.dev site. For a , pub clones the Git repository. Transitive dependencies are included, too. For example, if the js package depends on the test package, pub grabs both the js package and the package.

Pub creates a .packages file (under your app’s top directory) that maps each package name that your app depends on to the corresponding package in the system cache.

To import libraries found in packages, use the package: prefix:

import 'package:js/js.dart' as js;
import 'package:intl/intl.dart';

The Dart runtime takes everything after package: and looks it up within the .packages file for your app.

You can also use this style to import libraries from within your own package. Let’s say that the transmogrify package is laid out as follows:

The parser_test.dart file can import parser.dart like this:

import 'package:transmogrify/parser.dart';

The first time you get a new dependency for your package, pub downloads the latest version of it that’s compatible with your other dependencies. It then locks your package to always use that version by creating a lockfile. This is a file named pubspec.lock that pub creates and stores next to your pubspec. It lists the specific versions of each dependency (immediate and transitive) that your package uses.

When you’re ready to upgrade your dependencies to the latest versions, use the pub upgrade command:

The pub upgrade command tells pub to regenerate the lockfile, using the newest available versions of your package’s dependencies. If you want to upgrade only one dependency, you can specify the package to upgrade:

$ pub upgrade transmogrify

That command upgrades to the latest version but leaves everything else the same.

The command can’t always upgrade every package to its latest version, due to conflicting version constraints in the pubspec. To identify out-of-date packages that require editing the pubspec, use pub outdated.

The following pages have more information about packages and the pub package manager.

Publishing packages

The pub tool provides the following commands:

For an overview of all the pub commands, see the pub tool documentation.