Pub Package Manager

Package manager for Dart and Flutter

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:

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

Install Dependencies

# Install all dependencies
dart pub get

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

add

Add a new dependency to your project:

Runtime Dependency

# 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

# 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:

Dry Run

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

Publishing Checklist

Before publishing:

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

Global Packages

global activate

Install a package globally:

From pub.dev

# 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:

Tree View

# 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:

Add to Cache

# Download package to cache
dart pub cache add http

# Add specific version
dart pub cache add http 1.1.0

login/logout

Manage pub.dev authentication:

# Log in to pub.dev
dart pub login

# Log out
dart pub logout

token

Manage authentication tokens:

Add Token

# 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

Caret Syntax

# ^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

See Also

• pub.dev - Official package repository
• Package Layout Conventions - How to structure packages
• Publishing Packages - Publishing guide
• Dependency Management - Package management guide