The pub package manager isn’t just for using other people’s packages. It also allows you to share your packages with the world. If you have a useful project and you want others to be able to use it, use the pub publish command.

Preparing to publish

When publishing a package, it’s important to follow the pubspec format and package layout conventions. Some of these are required in order for others to be able to use your package. Others are suggestions to help make it easier for users to understand and work with your package. In both cases, pub tries to help you by pointing out what changes will help make your package play nicer with the Dart ecosystem. There are a few additional requirements for uploading a package:

• You must include a license file (named LICENSE, COPYING, or some variation) that contains an open-source license. We recommend the BSD license, which is used by Dart itself. You must also have the legal right to redistribute anything that you upload as part of your package.
• Your package must be less than 10 MB large after gzip compression. If it’s too large, consider splitting it into multiple packages, or cutting down on the number of included resources or examples.
• Your package should depend only on hosted dependencies (from the default pub package server) and SDK dependencies (sdk: flutter). These restrictions ensure that dependencies of your packages cannot become unavailable in the future.
• You must have a Google Account, which pub uses to manage package upload permissions. Your Google Account can be associated with a Gmail address or with any other email address.

Be aware that the email address associated with your Google account is displayed on the Pub site along with any packages you upload.

Important files

Pub uses the contents of a few files to create a page for your package at pub.dev/packages/<your_package>. Here are the files that affect how your package’s page looks:

• README: The README file (README, README.md, README.mdown, README.markdown) is the main content featured in your package’s page.
• CHANGELOG: Your package’s CHANGELOG (CHANGELOG, CHANGELOG.md, CHANGELOG.mdown, CHANGELOG.markdown), if found, will also be featured in a tab on your package’s page, so that developers can read it right from the Pub site.
• The pubspec: Your package’s pubspec.yaml file is used to fill out details about your package on the right side of your package’s page, like its description, authors, etc.

Publishing your package

For your first time around, you can perform a dry run:

Pub will check to make sure that your package follows the pubspec format and package layout conventions, and then upload your package to the Pub site. Pub will also show you all of the files it intends to publish. Here’s an example of publishing a package named transmogrify:

When you’re ready to publish your package, remove the --dry-run argument:

After your package has been successfully uploaded to Pub site, any pub user will be able to download it or depend on it in their projects. For example, if you just published version 1.0.0 of your transmogrify package, then another Dart developer can add it as a dependency in their pubspec.yaml:

What files are published?

All files in your package are included in the published package, with the following exceptions:

• Any packages directories.
• Your package’s lockfile.
• If you aren’t using Git, all hidden files (that is, files whose names begin with .).
• If you’re using Git, any files ignored by your .gitignore file.

Be sure to delete any files you don’t want to include (or add them to .gitignore). pub publish lists all files that it’s going to publish before uploading your package, so examine the list carefully before completing your upload.

Authors versus uploaders

The package authors as listed in the pubspec.yaml file are different from the list of people authorized to publish that package. Whoever publishes the first version of some package automatically becomes the first and only person authorized to upload additional versions of the package. To allow or disallow other people to upload versions, use the pub uploader command.

Publishing pre-releases

As you work on a package, consider publishing it as a pre-release. Pre-releases can be useful when any of the following are true:

• You’re actively developing the next major version of the package.
• You want beta testers for the next release candidate of the package.
• The package depends on an unstable version of the Dart or Flutter SDK.

As described in semantic versioning, to make a pre-release of a version, you append a suffix to the version. For example, to make a pre-release of version 2.0.0 you might use the version 2.0.0-dev.1. Later, when you release version 2.0.0, it will take precedence over all 2.0.0-XXX pre-releases.

Because pub prefers stable releases when available, users of a pre-release package might need to change their dependency constraints. For example, if a user wants to test pre-releases of version 2.1, then instead of ^2.0.0 or ^2.1.0 they might specify ^2.1.0-dev.1.

When a pre-release is published to pub.dev, the package page displays links to both the pre-release and the stable release. The pre-release doesn’t affect the analysis score, show up in search results, or replace the package README and documentation.

Publishing is forever

Keep in mind that publishing is forever. As soon as you publish your 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.

Resources

For more information, see the reference pages for:

• pub publish
• pub uploader