Custom package repositories

The pub tool has support for third-party package repositories. A package repository is an HTTP server from which the pub client can fetch packages. The official package repository is, this repository is by the pub tool by default. A package repository is identified by a hosted-url (e.g.

Third-party package servers can be useful for hosting private packages. It is also common to use git-dependencies for hosting private packages, however, the pub does not support resolving versions against a git-repository it just fetches a specific revision of the git-repository. Hence, when many people are collaborating it is sometimes preferable to use a private package repository.

Authenticating with a custom package repository

Custom package servers are often private and require authentication. The pub tool authenticates against package repositories by attaching a secret token to the requests. When the pub tool does not have a token for a given hosted-url it will attempt to make requests without authentication.

To specify a secret token for the pub tool to use with a given hosted-url, use the dart pub token add <hosted-url> command.

Getting dependencies from a custom package repository

To fetch a package from custom package repository we must specify the hosted-url for the package in pubspec.yaml, using the syntax for hosted packages.

    version: ^1.4.0

In the example above package:foo will be fetched from If authentication is required by this package repository, it can be specified using dart pub token add, which will prompt for the secret token.

Using multiple package repositories

It is possible to fetch different dependencies from different package repositories, as the hosted-url is specified for each dependency. As illustrated below.

  # package retry is fetched from (the default package repository)
  retry: ^3.0.0
  # package foo is fetched from
    version: ^1.4.0

This enables you to keep private packages on a private package repository while staying up-to-date with latest public dependencies. However, conflicts can easily arise if package retry requires meta from, and foo requires meta from Thus, if mirroing packages into a private package repository is it frequently necessary to also mirror all dependencies and either update the dependencies section in section in each package, or override the default package repository.

Overriding the default package repository

The package repository to be used can be specified on a per-dependency basis, or the default package repository can be overriden with the PUB_HOSTED_URL environment variable.

This can be useful if you are mirroring all packages in a private package repository, or working in a restricted network environment using a mirror of

Publishing to a custom package repository

The pub tool also supports publishing packages to a private package repository, using the publish_to property in pubspec.yaml. If working on a private package it is a good idea to specify this early in the development, so as to prevent accidental publication to

To publish a package to you would write a pubspec.yaml as follows, and run dart pub publish.

name: mypkg
version: 1.0.0
# Ensures the package is published to

Writing a custom package repository

The REST API for writing a custom package repository is outlined in the Hosted Pub Repository Specification Version 2.