pub: key concepts, Dart package manager and pubspec.yaml

What is pub?

pub (Package Universal Browser) — a built-in package manager that ships with the Dart SDK. It manages external libraries, resolves version conflicts, downloads transitive dependencies and caches packages locally. In the Flutter ecosystem, pub is used as the primary tool for adding navigation plugins, HTTP clients, state managers and other components.

pub's core functions include: installing dependencies from the pub.dev registry, local paths (path dependencies) and git repositories; version resolution according to semantic versioning rules; caching downloaded packages in a system directory; publishing your own packages to the public registry. All these operations are available via the dart pub CLI command or its equivalent flutter pub.

pub's architecture is based on a closed dependency graph: the manager builds a tree where each package appears exactly once. If two libraries require different versions of the same package, pub tries to find a compatible range or reports a conflict error. This differs from npm's approach, which allows multiple versions of the same package in different tree nodes.

pubspec.yaml Structure

The pubspec.yaml file — the central configuration file for any Dart or Flutter project. It is written in YAML format and contains metadata, dependencies, build configuration and SDK constraints. Below is a typical example for a Flutter application:

name: my_app
description: Example Flutter app
version: 1.0.0+1
publish_to: none

environment:
  sdk: ">=3.0.0 <4.0.0"
  flutter: ">=3.10.0"

dependencies:
  flutter:
    sdk: flutter
  http: ^1.1.0
  provider: ^6.0.5
  shared_preferences: ^2.2.0
  path_provider: ^2.1.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^3.0.0
  mockito: ^5.4.3

flutter:
  uses-material-design: true
  assets:
    - assets/images/
    - assets/fonts/

Key fields of pubspec.yaml: name — unique package name (Latin letters, underscores, digits only); description — brief description (required for publishing); version — semantic version with optional build number after plus sign; environment — minimum Dart SDK and Flutter SDK versions; dependencies — main application dependencies; dev_dependencies — development and test-only dependencies; flutter — Flutter configuration section (assets, fonts, plugins).

The publish_to field controls publishing availability: value none forbids publishing (typical for applications), default value — https://pub.dev. The dependency_overrides field allows forcibly overriding a package version in conflict situations — use with caution, only as a temporary solution.

Dependencies and Their Types

pub supports four types of dependencies, each specified with its own syntax inside pubspec.yaml:

Hosted

The standard type — the package is downloaded from the pub.dev registry or another compatible registry. Specify the package name and version. Example: http: ^1.1.0 will download the latest compatible version from the range >=1.1.0 and <2.0.0 according to caret versioning rules.

SDK Dependencies

Used to include the Flutter SDK or Dart SDK. Syntax: flutter: sdk: flutter. The package is taken from the local Flutter SDK installation, not from the registry. SDK dependencies are not versioned — their version is determined by the currently installed Flutter version.

Path

Point to a local directory containing a package. Useful when developing a library and testing without publishing. Syntax:

dependencies:
  my_local_lib:
    path: ../my_local_lib

Path dependencies are not pinned in pubspec.lock — each update re-resolves from the specified path.

Git

Allow including a package directly from a git repository. Branches, tags and commits are supported:

dependencies:
  my_git_lib:
    git:
      url: https://github.com/user/my_git_lib.git
      ref: main

Git dependencies are convenient for forks, unpublished fixes or working on Pull Requests. It is recommended to specify a specific tag or commit instead of a branch to avoid unexpected changes during builds.

Versioning and Ranges

pub strictly follows Semantic Versioning 2.0: format MAJOR.MINOR.PATCH, where MAJOR — incompatible changes, MINOR — backward-compatible additions, PATCH — backward-compatible fixes. Based on this scheme, pub determines package compatibility and resolves conflicts.

Three main operators are used for specifying versions in pubspec.yaml:

• Caret (^) — ^1.2.3 is equivalent to >=1.2.3 and <2.0.0. The most common operator, as it implies compatibility within the major version. For packages with major version 0 (zero) — ^0.1.2 means >=0.1.2 and <0.2.0, which follows SemVer rules for unstable versions.
• Tilde (~) — ~1.2.3 is equivalent to >=1.2.3 and <1.3.0. Pins the minor version, allowing only patch updates. Used less frequently, mainly when incompatibility at the minor version level is known.
• Exact range — >=1.2.0 <2.0.0 — explicit notation providing full control. Useful for complex constraints, for example when using multiple versions of transitive dependencies.

After running dart pub get, pub generates a pubspec.lock file that pins the exact versions of all resolved packages (both direct and transitive). This file must be included in version control to ensure reproducible builds across all machines. When running dart pub upgrade, the lock file is updated to the latest compatible versions within the specified constraints.

A dependency conflict error occurs when two packages require non-overlapping ranges of the same dependency. pub reports which packages are in conflict and why. Solution: update one of the conflicting packages to a compatible version, use dependency_overrides (temporary measure) or switch to an alternative package.

Essential pub Commands

All pub operations are performed via a unified CLI interface. The Dart SDK uses the dart pub command, the Flutter SDK uses the equivalent flutter pub (additionally accounts for Flutter SDK dependencies and plugins). Below are the key commands:

• dart pub get — downloads all dependencies specified in pubspec.yaml, resolves versions and creates/updates pubspec.lock. Run when first cloning a project or after changing dependencies.
• dart pub upgrade — updates all dependencies to the latest versions within the pubspec.yaml constraints and overwrites pubspec.lock. A single package can be updated: dart pub upgrade http.
• dart pub add <package> — adds a new dependency to pubspec.yaml and immediately runs pub get. Example: dart pub add dio adds the latest version of the dio package.
• dart pub remove <package> — removes a dependency from pubspec.yaml and restarts graph resolution.
• dart pub cache repair — reloads all cached packages. Helps when the local cache is corrupted or checksum errors occur.
• dart pub deps — prints the dependency tree in a convenient text format. Useful for analyzing transitive dependencies and finding duplicates.
• dart pub publish — publishes the current package to pub.dev. Before publishing, validates the pubspec.yaml, license and description.
• dart pub outdated — shows a list of outdated dependencies indicating the current, desired and latest available version. Analogous to npm outdated.

All commands are also available in shortened form dart pub get as dart pub g (not all shortenings). In Flutter projects, commands are prefixed with flutter: flutter pub get, flutter pub add and so on. The Flutter version additionally checks plugin compatibility with the target platform.

Publishing on pub.dev

pub.dev — the central package registry for the Dart and Flutter ecosystem. As of January 2025, over 50,000 packages have been published there, with total downloads exceeding 10 billion. Each package has a page with description, documentation, popularity scores, Pub Points ratings and versions.

Pub Points — an automated package quality scoring system from 0 to 130 points. It considers: license presence, description, examples, compatibility with the latest stable Dart version, absence of vulnerabilities, test coverage, formatting correctness. A high score increases the package's visibility in search and user trust.

The publishing process includes several steps:

1. Check pubspec.yaml: ensure name, description, version, license are present (SPDX identifier recommended, e.g. MIT).
2. Run dart pub publish --dry-run — a dry run without sending to the server, displays all files that will be included in the package and possible errors.
3. Authenticate via Google account on first publish: dart pub publish will open a browser for OAuth authentication.
4. Confirm publishing in the terminal. After successful upload, the package appears on pub.dev within a few minutes.

Important rules: only packages with a unique name can be published; once published, a version cannot be deleted (only hidden — dart pub unpublish — within 7 days); for major updates, follow Semantic Versioning rules, do not break the public API without changing the major version.