Pub Package Manager

Pub is the package manager for Dart, helping you manage dependencies, publish packages, and organize your Dart projects.

Overview

Pub provides commands for:

Installing and managing dependencies
Publishing packages to pub.dev
Running executables from packages
Managing global packages

Usage

dart pub <subcommand> [arguments]

Core Commands

get

Install or update dependencies:

dart pub get

This command:

Reads pubspec.yaml
Resolves dependencies
Downloads packages to .pub-cache
Creates/updates pubspec.lock
Generates .dart_tool/package_config.json

# Install all dependencies
dart pub get

# Offline mode (use cached packages only)
dart pub get --offline

add

Add a new dependency to your project:

# Add to dependencies
dart pub add http

# Add with version constraint
dart pub add http:^1.0.0

# Add multiple packages
dart pub add http path collection

remove

Remove a dependency:

# Remove from dependencies
dart pub remove http

# Remove dev dependency
dart pub remove --dev test

upgrade

Upgrade dependencies to the latest compatible versions:

# Upgrade all dependencies
dart pub upgrade

# Upgrade and update pubspec.yaml constraints
dart pub upgrade --major-versions

outdated

Check for outdated dependencies:

dart pub outdated

Example output:

Dependencies
  http 0.13.5 → 1.1.0 (1.2.0 available)
  path 1.8.0 → 1.8.3

Dev dependencies
  test 1.24.0 → 1.24.3

Transitive dependencies  
  async 2.9.0 → 2.11.0

downgrade

Downgrade to the lowest allowed versions:

dart pub downgrade

Useful for testing minimum version compatibility.

Publishing

publish

Publish a package to pub.dev:

# Check what would be published
dart pub publish --dry-run

Publishing Checklist

Before publishing:

Update version in pubspec.yaml
Update CHANGELOG.md
Run tests: dart test
Check formatting: dart format --output=none --set-exit-if-changed .
Analyze code: dart analyze
Dry run: dart pub publish --dry-run
Publish: dart pub publish

Global Packages

global activate

Install a package globally:

# Activate from pub.dev
dart pub global activate webdev

# Activate specific version
dart pub global activate webdev 3.0.0

global run

Run a globally activated package:

dart pub global run webdev serve

# Or use the executable directly (if in PATH)
webdev serve

global deactivate

Deactivate a global package:

dart pub global deactivate webdev

global list

List globally activated packages:

dart pub global list

Example output:

webdev 3.0.0
stagehand 4.0.0

Other Commands

deps

Show dependency graph:

# Show dependency tree
dart pub deps

Example output:

my_app 1.0.0
├── http 1.1.0
│   ├── async 2.11.0
│   ├── http_parser 4.0.2
│   └── meta 1.9.1
└── path 1.8.3

cache

Manage the package cache:

# Download package to cache
dart pub cache add http

# Add specific version
dart pub cache add http 1.1.0

Manage pub.dev authentication:

# Log in to pub.dev
dart pub login

# Log out
dart pub logout

token

Manage authentication tokens:

# Add authentication token
dart pub token add

Configuration

pubspec.yaml

The package configuration file:

pubspec.yaml

name: my_app
description: A sample Dart application
version: 1.0.0

environment:
  sdk: ^3.0.0

dependencies:
  http: ^1.1.0
  path: ^1.8.0
  
dev_dependencies:
  test: ^1.24.0
  build_runner: ^2.4.0

Dependency Types

Regular Dependencies

dependencies:
  # pub.dev packages
  http: ^1.1.0
  
  # Git dependencies
  my_package:
    git:
      url: https://github.com/user/my_package.git
      ref: main
  
  # Path dependencies  
  local_package:
    path: ../local_package
  
  # Hosted dependencies (alternative repository)
  custom_package:
    hosted:
      name: custom_package
      url: https://my-repo.com
    version: ^1.0.0

Dev Dependencies

Used only during development:

dev_dependencies:
  test: ^1.24.0
  build_runner: ^2.4.0
  mockito: ^5.4.0

Dependency Overrides

Force specific versions:

dependency_overrides:
  http: 1.0.0
  path: 1.8.2

Version Constraints

# ^1.2.3 means >=1.2.3 <2.0.0
dependencies:
  http: ^1.1.0

pubspec.lock

Lock file with exact versions:

pubspec.lock

packages:
  http:
    dependency: "direct main"
    description:
      name: http
      url: "https://pub.dev"
    source: hosted
    version: "1.1.0"

Important: Commit pubspec.lock for applications, but not for libraries.

Environment Variables

PUB_CACHE

Set the package cache location:

export PUB_CACHE="$HOME/.pub-cache"

PUB_HOSTED_URL

Use an alternative package repository:

export PUB_HOSTED_URL="https://my-pub-server.com"

Best Practices

1. Commit pubspec.lock

# For applications
git add pubspec.lock
git commit -m "Lock dependencies"

# For libraries - add to .gitignore
echo "pubspec.lock" >> .gitignore

2. Use Version Constraints

# Good: Allows compatible updates
dependencies:
  http: ^1.1.0

# Bad: Too restrictive
dependencies:
  http: 1.1.0

# Bad: Too permissive
dependencies:
  http: any

3. Regular Updates

# Check for outdated packages weekly
dart pub outdated

# Update regularly
dart pub upgrade

4. Clean Development

# Remove and reinstall dependencies
rm -rf .dart_tool/ .packages
dart pub get

CI/CD Integration

GitHub Actions

.github/workflows/dart.yml

name: Dart CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: dart-lang/setup-dart@v1
      
      - name: Install dependencies
        run: dart pub get
      
      - name: Verify dependencies
        run: dart pub outdated --exit-code
      
      - name: Run tests
        run: dart test

Cache Dependencies

.github/workflows/dart.yml

- name: Cache dependencies
  uses: actions/cache@v3
  with:
    path: ~/.pub-cache
    key: ${{ runner.os }}-pub-${{ hashFiles('**/pubspec.lock') }}
    restore-keys: |
      ${{ runner.os }}-pub-

Troubleshooting

Clear Cache

# Remove all cached packages
dart pub cache clean

# Reinstall dependencies
dart pub get

Repair Cache

# Repair corrupted cache
dart pub cache repair

Resolve Conflicts

# See dependency resolution
dart pub deps

# Try upgrading
dart pub upgrade

# Use dependency overrides as last resort

Version Solve Failed

# Check constraints
dart pub outdated

# Try with --major-versions
dart pub upgrade --major-versions

# Use dependency_overrides if needed

Examples

New Project Setup

# Create project
dart create my_app
cd my_app

# Add dependencies
dart pub add http args
dart pub add --dev test

# Install
dart pub get

Publishing a Package

# Prepare package
dart format .
dart analyze
dart test

# Dry run
dart pub publish --dry-run

# Publish
dart pub publish

Using Global Tools

# Install webdev
dart pub global activate webdev

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$PATH:$HOME/.pub-cache/bin"

# Use webdev
webdev serve

Getting Started

Building the SDK

Core Concepts

Compilers

Core Libraries

Runtime & VM

Tools & CLI

Development

​Overview

​Usage

​Core Commands

​get

​add

​remove

​upgrade

​outdated

​downgrade

​Publishing

​publish

​Publishing Checklist

​Global Packages

​global activate

​global run

​global deactivate

​global list

​Other Commands

​deps

​cache

​login/logout

​token

​Configuration

​pubspec.yaml

​Dependency Types

​Regular Dependencies

​Dev Dependencies

​Dependency Overrides

​Version Constraints

​pubspec.lock

​Environment Variables

​PUB_CACHE

​PUB_HOSTED_URL

​Best Practices

​1. Commit pubspec.lock

​2. Use Version Constraints

​3. Regular Updates

​4. Clean Development

​CI/CD Integration

​GitHub Actions

​Cache Dependencies

​Troubleshooting

​Clear Cache

​Repair Cache

​Resolve Conflicts

​Version Solve Failed

​Examples

​New Project Setup

​Publishing a Package

​Using Global Tools

​See Also

Build docs developers (and LLMs) love

Overview

Usage

Core Commands

get

add

remove

upgrade

outdated

downgrade

Publishing

publish

Publishing Checklist

Global Packages

global activate

global run

global deactivate

global list

Other Commands

deps

cache

login/logout

token

Configuration

pubspec.yaml

Dependency Types

Regular Dependencies

Dev Dependencies

Dependency Overrides

Version Constraints

pubspec.lock

Environment Variables

PUB_CACHE

PUB_HOSTED_URL

Best Practices

1. Commit pubspec.lock

2. Use Version Constraints

3. Regular Updates

4. Clean Development

CI/CD Integration

GitHub Actions

Cache Dependencies

Troubleshooting

Clear Cache

Repair Cache

Resolve Conflicts

Version Solve Failed

Examples

New Project Setup

Publishing a Package

Using Global Tools

See Also