Package dependencies

Dependencies are one of the core concepts of the pub package manager.A dependency is another package that your package needs in order to work.Dependencies are specified in your pubspec.You only listimmediate dependencies—thesoftware that your package uses directly. Pub handlestransitive dependencies for you.

To see all the dependencies used by a package, usepub deps.

For each dependency, you specify the name of the package you depend on.For library packages,you specify the range of versions of that package that you allow.You may also specify thesource which tells pub how the package can be located,and any additional description that the source needs to find the package.

Based on what data you want to provide, you can specify dependencies in twoways. The shortest way is to just specify a name:

  1. dependencies:
  2.   transmogrify:

This creates a dependency on transmogrify that allows any version, and looksit up using the default source, which is the pub.dev site.To limit the dependency to a range of versions,you can provide a version constraint:

  1. dependencies:
  2.   transmogrify: ^1.0.0

This creates a dependency on transmogrify using the default source andallowing any version from 1.0.0 to 2.0.0 (but not including 2.0.0). SeeVersion constraints and Caret syntaxfor details on the version constraint syntax.

If you want to specify a source, the syntax looks a bit different:

  1. dependencies:
  2.   transmogrify:
  3.     hosted:
  4.       name: transmogrify
  5.       url: http://some-package-server.com

This depends on the transmogrify package using the hosted source.Everything under the source key (here, just a map with a url: key) is thedescription that gets passed to the source. Each source has its own descriptionformat, detailed below.

You can also provide a version constraint:

  1. dependencies:
  2.   transmogrify:
  3.     hosted:
  4.       name: transmogrify
  5.       url: http://some-package-server.com
  6.     version: ^1.0.0

This long form is used when you don’t use the default source or when you have acomplex description you need to specify.But in most cases, you’ll just use the simplepackagename: version form.

Dependency sources

Here are the different sources pub can use to locate packages, and thedescriptions they allow:

SDK

The SDK source is used for any SDKs that are shipped along with packages,which may themselves be dependencies.Currently, Flutter is the only SDK that is supported.

The syntax looks like this:

  1. dependencies:
  2.   flutter_driver:
  3.     sdk: flutter
  4.     version: ^0.0.1

The identifier after sdk: indicates which SDK the package comes from.If it’s flutter, the dependency is satisfiable as long as:

  • Pub is running in the context of the flutter executable
  • The Flutter SDK contains a package with the given name
  • That package’s version matches the version constraint

If it’s an unknown identifier, the dependency is always considered unsatisfied.

A package with an sdk dependencymust have a Dart SDK constraint with a minimum version of at least 1.19.0.This constraint ensures that older versions of pub won’tinstall packages that have sdk dependencies.

Hosted packages

A hosted package is one that can be downloaded from the pub.dev site(or another HTTP server that speaks the same API). Here’s an exampleof declaring a dependency on a hosted package:

  1. dependencies:
  2.   transmogrify: ^1.4.0

This example specifies that your package depends on a hosted package namedtransmogrify and will work with any version from 1.4.0 to 2.0.0(but not 2.0.0 itself).

If you want to use your own package server, you can use a description thatspecifies its URL:

  1. dependencies:
  2.   transmogrify:
  3.     hosted:
  4.       name: transmogrify
  5.       url: http://your-package-server.com
  6.     version: ^1.4.0

Git packages

Sometimes you live on the bleeding edge and need to use packages thathaven’t been formally released yet. Maybe your package itself is still indevelopment and is using other packages that are being developed at thesame time. To make that easier, you can depend directly on a packagestored in a Git repository.

  1. dependencies:
  2.   kittens:
  3.     git: git://github.com/munificent/kittens.git

The git here says this package is found using Git, and the URL after that isthe Git URL that can be used to clone the package.

Even if the package repo is private, if you canconnect to the repo using SSH,then you can depend on the package by using the repo’s SSH URL:

  1. dependencies:
  2.   kittens:
  3.     git: git@github.com:munificent/kittens.git

If you want to depend on a specific commit, branch, or tag,add a ref argument:

  1. dependencies:
  2.   kittens:
  3.     git:
  4.       url: git://github.com/munificent/kittens.git
  5.       ref: some-branch

The ref can be anything that Git allows to identify a commit.

Pub assumes that the package is in the root of the Git repository.To specify a different location in the repo, use the path argument:

  1. dependencies:
  2.   kittens:
  3.     git:
  4.       url: git://github.com/munificent/cats.git
  5.       path: path/to/kittens

The path is relative to the Git repo’s root.

Path packages

Sometimes you find yourself working on multiple related packages at the sametime. Maybe you are creating a framework while building an app that uses it.In those cases, during development you really want to depend on the _live_version of that package on your local file system. That way changes in onepackage are instantly picked up by the one that depends on it.

To handle that, pub supports path dependencies.

  1. dependencies:
  2.   transmogrify:
  3.     path: /Users/me/transmogrify

This says the root directory for transmogrify is /Users/me/transmogrify.For this dependency, pub generates a symlink directly to the lib directoryof the referenced package directory. Any changes you make to the dependentpackage are seen immediately. You don’t need to run pub every time youchange the dependent package.

Relative paths are allowed and are considered relative to the directorycontaining your pubspec.

Path dependencies are useful for local development, but do not work whensharing code with the outside world—not everyone can get toyour file system. Because of this, you cannot upload a package to thepub.dev site if it has any path dependencies in its pubspec.

Instead, the typical workflow is:

  • Edit your pubspec locally to use a path dependency.
  • Work on the main package and the package it depends on.
  • Once they’re both working, publish the dependent package.
  • Change your pubspec to point to the now hosted version of its dependent.
  • Publish your main package too, if you want.

Version constraints

If your package is an application, you don’t usually need to specify versionconstraints for your dependencies. Youtypically want to use the latest versions of the dependencies when you firstcreate your app. Then you’ll create and check in alockfile that pins your dependencies to those specificversions. Specifying version constraints in your pubspec then is usuallyredundant (though you can do it if you want).

For a library package that you want users toreuse, though, it is important to specify version constraints. That lets peopleusing your package know which versions of its dependencies they can rely on tobe compatible with your library. Your goal is to allow a range of versions aswide as possible to give your users flexibility. But it should be narrow enoughto exclude versions that you know don’t work or haven’t been tested.

The Dart community uses semantic versioning1, which helps you know which versions should work.If you know that your package works fine with 1.2.3 of some dependency, thensemantic versioning tells you that it should work (at least) up to 2.0.0.

A version constraint is a series of:

  • any
  • The string any allows any version. This is equivalent to an emptyversion constraint, but is more explicit. While any is allowed,we do not recommend it for performance reasons.
  • 1.2.3
  • A concrete version number pins the dependency to only allow that exact version. Avoid using this when you can because it can cause version lock for your users and make it hard for them to use your package along with other packages that also depend on it.
  • >=1.2.3
  • Allows the given version or any greater one. You’ll typically use this.
  • >1.2.3
  • Allows any version greater than the specified one but not thatversion itself.
  • <=1.2.3
  • Allows any version lower than or equal to the specified one. Youwon’t typically use this.
  • <1.2.3
  • Allows any version lower than the specified one but not thatversion itself. This is what you’ll usually use because it lets you specifythe upper version that you know does not work with your package(because it’s the first version to introduce some breaking change).

You can specify version parts as you want, and their ranges are intersectedtogether. For example, '>=1.2.3 <2.0.0' allows any version from 1.2.3 to2.0.0 excluding 2.0.0 itself. An easier way to express this range isby using caret syntax, or ^1.2.3.

If the > character is in the version constraint,be sure to quote the constraint string,so the character isn’t interpreted as YAML syntax.For example, never use >=1.2.3 <2.0.0;instead, use '>=1.2.3 <2.0.0' or ^1.2.3.

Caret syntax

Caret syntax provides a more compact way of expressing the most commonsort of version constraint.^version means “the range of all versions guaranteed to be backwardscompatible with the specified version”, and follows pub’s convention forsemantic versioning.For example, ^1.2.3 is equivalent to '>=1.2.3 <2.0.0', and^0.1.2 is equivalent to '>=0.1.2 <0.2.0'.The following is an example of caret syntax:

  1. dependencies:
  2.   path: ^1.3.0
  3.   collection: ^1.1.0
  4.   string_scanner: ^0.1.2

Note that caret syntax was added in Dart 1.8.3. Older versions of Dartdon’t understand it, so you’ll need to include an SDK constraint (usingtraditional syntax) to ensure that older versions of pub will not tryto process it. For example:

  1. environment:
  2.   sdk: '>=1.8.3 <3.0.0'

Dev dependencies

Pub supports two flavors of dependencies: regular dependencies and devdependencies. Dev dependencies differ from regular dependencies in that devdependencies of packages you depend on are ignored. Here’s an example:

Say the transmogrify package uses the test package in its tests and onlyin its tests. If someone just wants to use transmogrify—import itslibraries—it doesn’t actually need test. In this case, it specifiestest as a dev dependency. Its pubspec will have something like:

  1. dev_dependencies:
  2.   test: '>=0.5.0 <0.12.0'

Pub gets every package that your package depends on, and everything those_packages depend on, transitively. It also gets your package’s dev dependencies,but it _ignores the dev dependencies of any dependent packages. Pub only getsyour package’s dev dependencies. So when your package depends ontransmogrify it will get transmogrify but not test.

The rule for deciding between a regular or dev dependency is simple: Ifthe dependency is imported from something in your lib or bin directories,it needs to be a regular dependency. If it’s only imported from test,example, etc. it can and should be a dev dependency.

Using dev dependencies makes dependency graphs smaller. That makes pub runfaster, and makes it easier to find a set of package versions that satisfies allconstraints.

Dependency overrides

You can use dependency_overrides to temporarily override all referencesto a dependency.

For example, perhaps you are updating a local copy of transmogrify, apublished library package. Transmogrify is used by other packages in yourdependency graph, but you don’t want to clone each package locallyand change each pubspec to test your local copy of transmogrify.

In this situation, you can override the dependency usingdependency_overrides to specify the directory holding the localcopy of the package.

The pubspec would look something like the following:

  1. name: my_app
  2. dependencies:
  3.   transmogrify: ^1.2.0
  4. dependency_overrides:
  5.   transmogrify:
  6.     path: ../transmogrify_patch/

When you run pub get, the pubspec’s lockfile is updated to reflect thenew path to your dependency and, whereever transmogrify is used, pubuses the local version instead.

You can also use dependency_overrides to specify a particularversion of a package:

  1. name: my_app
  2. dependencies:
  3.   transmogrify: ^1.2.0
  4. dependency_overrides:
  5.   transmogrify: '3.2.1'

Caution: Using a dependency override involves some risk. For example,using an override to specify a version outside the range that thepackage claims to support, or using an override to specifya local copy of a package that has unexpected behaviors,may break your application.

[1] Pub follows version 2.0.0-rc.1 of the semantic versioning spec,because that version allows packages to use build identifiers (+12345)to differentiate versions. ↩