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.dev 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.

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

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 dart pub get to retrieve 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:

name: my_app

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

name: my_app
​
dependencies:
  intl: ^0.20.2
  path: ^1.9.1

To update the pubspec.yaml file, without manual editing, you can run dart pub add command. The following example adds a dependency on vector_math.

$ dart pub add vector_math
Resolving dependencies...
+ vector_math 2.1.3
Downloading vector_math 2.1.3...
Changed 1 dependency!

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 dart pub get from the top directory of your application:

$ cd <path-to-my_app>
$ dart pub get

This process is called getting the dependencies.

The dart 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 pub.dev site. For a Git dependency, 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 test package.

Pub creates a package_config.json file (under the .dart_tool/ 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 package_config.json 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:

transmogrify/
  lib/
    transmogrify.dart
    parser.dart
  test/
    parser/
      parser_test.dart

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.

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 its dependencies. 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 the dart pub upgrade command:

$ dart pub upgrade

The dart 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:

$ dart pub upgrade transmogrify

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

The dart pub upgrade 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 dart pub outdated.

In some situations, dart pub get does not retrieve the exact package versions locked in the pubspec.lock file:

• If new dependencies are added to or removed from pubspec.yaml after the pubspec.lock file was last updated.
• If the locked version no longer exists in the package repository.
• If you changed to a different version of the Dart SDK, and some packages are no longer compatible with that new version.

In these cases dart pub get will:

• Unlock enough of the locked dependency versions that a resolution becomes possible.
• Notify you about any dependency changes relative to the existing pubspec.lock .

For example, after adding retry: ^3.0.0 to your dependencies:

$ dart pub get
Resolving dependencies... (1.0s)
Downloading packages...
+ retry 3.1.2

Also, if the content hash of a published package version differs from the hash in the pubspec.lock file, pub will warn you and update the lockfile to reflect the published version.

For example, if you manually change the hash of retry in pubspec.lock:

$ dart pub get
Resolving dependencies...
Downloading packages...
~ retry 3.1.2 (was 3.1.2)
The existing content-hash from pubspec.lock doesn't match contents for:
 * retry-3.1.2 from "https://pub.dev"

This indicates one of:
 * The content has changed on the server since you created the pubspec.lock.
 * The pubspec.lock has been corrupted.

The content-hashes in pubspec.lock has been updated.

For more information see:
https://dart.dev/go/content-hashes
Changed 1 dependency!

When deploying your project to production, use dart pub get --enforce-lockfile to retrieve dependencies.

If your project's dependency constraints can't be satisfied with the exact versions and content hashes in pubspec.lock, package retrieval and the command will fail. This helps avoid deploying untested dependencies and dependency versions to production.

$ dart pub get --enforce-lockfile
Resolving dependencies...
Downloading packages...
~ retry 3.1.2 (was 3.1.2)
The existing content-hash from pubspec.lock doesn't match contents for:
 * retry-3.1.2 from "https://pub.dev"

This indicates one of:
 * The content has changed on the server since you created the pubspec.lock.
 * The pubspec.lock has been corrupted.

For more information see:
https://dart.dev/go/content-hashes
Would change 1 dependency.
Unable to satisfy `pubspec.yaml` using `pubspec.lock`.

To update `pubspec.lock` run `dart pub get` without `--enforce-lockfile`.

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

• Creating packages
• Publishing packages
• Pub workspaces (monorepo support)

• Pub dependencies
• Pub environment variables
• Pub package layout conventions
• Pub versioning philosophy
• Pubspec format
• Glossary with pub terms

The dart pub tool provides the following subcommands:

• add
• cache
• deps
• downgrade
• get
• global
• outdated
• publish
• remove
• token
• unpack
• upgrade

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

Troubleshooting pub gives solutions to problems that you might encounter when using pub.