- Installing and configuring pub
- Creating a package
- Adding a dependency
- Getting dependencies
- Importing code from a dependency
- Upgrading a dependency
- Publishing a package
Pub is a package manager for Dart. It helps you reuse existing Dart code and bundle your Dart apps and libraries so that you can reuse and share them with other people. Pub handles versioning and dependency management so that you can ensure that your app runs on other machines exactly the same as it does on yours.
To find a package that’s on pub.dartlang.org, use the Search box at the top right of this page.
To use a package that’s on pub.dartlang.org:
pubspec.yamlfile (if one doesn’t already exist) and list the package as dependency. For example, to use the web_ui package in an app, put this in a top-level file named
name: my_app dependencies: web_ui: any
pub get, either on the command line or through the Dart Editor menu: Tools > Pub Get.
Import one or more libraries from the package:
For details and pointers to more documentation, read on.
Installing and configuring pub
Pub is in the Dart SDK,
which you can download by itself or as part of
You can use pub through
Dart Editor, or through the
pub command-line app, which lives inside the
bin directory of the Dart SDK.
To use pub and other tools on the command line,
you might want to add the SDK’s
bin directory to your system path.
For example, on Mac and Linux:
export PATH=$PATH:<path to sdk>/bin
<path to sdk> is the absolute path
to the main directory of the SDK. For example,
if you install Dart Editor in
/home/me/dart, then add this to your PATH:
On Windows, you can set the system PATH environment variable through the Control Panel. A quick search should find the instructions for your version of Windows.
Creating a package
A package in pub is a directory that contains Dart code and any other stuff that goes along with it like resources, tests, and docs. Frameworks and reusable libraries are obviously packages, but applications are too. If your app wants to use pub packages, it needs to be a package too.
While everything is a package in pub, there are two flavors of packages that are used slightly differently in practice. A library package is a package that is intended to be reused by other packages. It will usually have code that other packages import, and it will likely be hosted somewhere that people can get to. An application package only consumes packages but doesn’t itself get reused. In other words, library packages will be used as dependencies, but application packages won’t.
In most cases, there’s no difference between the two and we’ll just say “package”. In the few places where it does matter, we’ll specify “library package” or “application package”.
To turn your app into an application package so it can use other packages, you
just need to give it a pubspec. This file is written using the
YAML language and is named
pubspec.yaml. The simplest
possible pubspec just contains the name of the package. Save the pubspec file as
pubspec.yaml in the root directory of your app.
Behold, the simplest possible
my_app is a pub package!
Adding a dependency
One of pub’s main jobs is managing dependencies. A dependency is just
another package that your package relies on. If your app is using some
transformation library called “transmogrify”, then your app package will depend
You specify your package’s dependencies in the pubspec file immediately after your package name. For example:
name: my_app dependencies: transmogrify:
Here, we are declaring a dependency on the (fictional)
Once you’ve declared a dependency, you then tell pub to get it for you. If you’re using the Editor, select “Pub Get” from the “Tools” menu. If you’re rocking the command line, do:
$ cd path/to/your_app $ pub get
When you do this, pub will create a
packages directory in the same directory
pubspec.yaml. In there, it will place each package that your package
depends on (these are called your immediate dependencies). It will also
look at all of those packages and get everything they depend on, recursively
(these are your transitive dependencies).
When this is done, you will have a
packages directory that contains every
single package your program needs in order to run.
Importing code from a dependency
Now that you have a dependency wired up, you want to be able to use code from
it. To access a library in a another package, you will import it using the
This looks inside the
transmogrify package for a top-level file named
transmogrify.dart. Most packages just define a single entrypoint whose name
is the same as the name of the package. Check the documentation for the package
to see if it exposes anything different for you to import.
You can also use this style to import libraries from within your own package. For example, let’s say your package is laid out like:
transmogrify/ lib/ transmogrify.dart parser.dart test/ parser/ parser_test.dart
parser_test file could import
parser.dart like this:
But that’s a pretty nasty relative path. If
parser_test.dart is ever moved
up or down a directory, that path will break and you’ll have to fix the code.
Instead, you can do:
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 will download 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 this is an application package, you will check this file into source control. That way, everyone hacking on your app ensures they are using the same versions of all of the packages. This also makes sure you use the same versions of stuff when you deploy your app to production.
When you are ready to upgrade your dependencies to the latest versions, do:
$ pub upgrade
This tells pub to regenerate the lockfile using the newest available versions of your package’s dependencies. If you only want to upgrade a specific dependency, you can specify that too:
$ pub upgrade transmogrify
transmogrify to the latest version but leaves everything else
Publishing a package
Pub isn’t just for using other people’s packages. It also allows you to share your packages with the world. Once you’ve written some useful code and you want everyone else to be able to use it, just run:
$ pub publish
Pub will check to make sure that your package follows the pubspec
format and package layout conventions, and
then upload your package to pub.dartlang.org. Then
any Pub user will be able to download it or depend on it in their pubspecs. For
example, if you just published version 1.0.0 of a package named
then they can write:
dependencies: transmogrify: ">= 1.0.0 < 2.0.0"
Keep in mind that publishing is forever. As soon as you publish your awesome package, users will be able to depend on it. Once they start doing that, removing the package would break theirs. To avoid that, pub strongly discourages deleting packages. You can always upload new versions of your package, but old ones will continue to be available for users that aren’t ready to upgrade yet.