How to use packages
The Dart ecosystem uses packages to manage shared software such as libraries and tools. To get Dart packages, you use the pub package manager. You can find publicly available packages on the Pub site, or you can load packages from the local file system or elsewhere, such as Git repositories. Wherever your packages come from, pub manages version dependencies, helping you get package versions that work with each other and with your SDK version.
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.yamlthat lists package dependencies and includes other metadata, such as a name for your package).
- Use pub to get your package’s dependencies.
- If your Dart code depends on a library in the package, import the library.
Creating a pubspec
The pubspec is a file named
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 (
intl) that are hosted on the Pub site:
name: my_app dependencies: js: ^0.6.0 intl: ^0.15.8
For details on creating a pubspec, see the pubspec documentation and the documentation for the packages that you want to use.
Once you have a pubspec, you can run
get from the top directory of your application:
$ cd <path-to-my_app> $ pub get
This process is called getting the dependencies.
pub get command determines which packages your app depends on,
and puts them in a central system cache.
If your app depends on a published package, pub downloads that package from the
For a Git dependency,
pub clones the Git repository.
Transitive dependencies are included, too.
For example, if the
js package depends on the
grabs both the
js package and the
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.
Importing libraries from packages
To import libraries found in packages, use the
import 'package:js/js.dart' as js; import 'package:intl/intl.dart';
The Dart runtime takes everything after
and looks it up within the
.packages file for
You can also use this style to import libraries from within your own package.
Consider the following pubspec file, which declares a dependency on
name: my_app dependencies: transmogrify:
Let’s say that your package is laid out as follows:
transmogrify/ lib/ transmogrify.dart parser.dart test/ parser/ parser_test.dart
parser_test file could import
parser.dart like this:
But that’s a fragile relative path. If
parser_test.dart ever moves
up or down a directory, that path breaks.
Instead, you can do as follows:
This way, the import can always get to
parser.dart regardless of where the
importing file is.
Upgrading a dependency
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.
If your package is an application package, you should check this file into source control. That way, everyone working on your app uses the same versions of all of the packages. Checking in the lockfile also ensures that your deployed app uses the same versions of code.
When you’re ready to upgrade your dependencies to the latest versions, use pub upgrade:
$ pub upgrade
That 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
transmogrify to the latest version
but leaves everything else the same.
The following pages have more information about packages and the pub package manager.
- Pub dependencies
- Pub environment variables
- Pub glossary
- Pub package layout conventions
- Pub versioning philosophy
- Pubspec format
pub tool provides the following commands:
For an overview of all the
see the pub tool documentation.
Troubleshooting pub gives solutions to problems that you might encounter when using pub.