Introduction

Keeping the Dart SDK up to date is essential for accessing the latest language features, performance improvements, and security patches. This How to Upgrade Dart SDK guide walks you through every method you might need, from local development machines to CI/CD pipelines.

Why Upgrade the Dart SDK?

New releases bring:

  • Improved null‑safety tooling
  • Faster compilation times
  • New language constructs (e.g., pattern matching, records)
  • Bug fixes and security updates

Staying current also ensures compatibility with the latest Flutter releases, which often depend on a minimum Dart version.

Prerequisites

  • Flutter installed (recommended, because Flutter bundles a compatible Dart SDK)
  • Access to a terminal or command prompt
  • Version control (Git) to revert if needed

Step 1 – Check Your Current Dart SDK Version

Run the following command in any terminal:

Code
dart --version

Typical output looks like:

Code
Dart SDK version: 3.2.0 (stable) (Tue Sep 12 12:00:00 2024 +0000) on "macos_x64"

Step 2 – Upgrade via Flutter (Recommended)

Flutter ships its own Dart SDK, so upgrading Flutter automatically upgrades Dart to a compatible version.

Code
flutter upgrade

After the upgrade, verify the bundled Dart version:

Code
flutter doctor -v

The output includes a line similar to:

JSON
[✓] Flutter (Channel stable, 3.22.0, on macOS 13.6.2 22G91)
    • Dart version 3.3.0
Tip: If you only need the Dart SDK without the full Flutter toolchain, consider using a dedicated package manager (see Step 3).

Step 3 – Upgrade the Standalone Dart SDK

If you installed Dart separately (e.g., via Homebrew, Chocolatey, or asdf), follow the appropriate method.

Homebrew (macOS/Linux)

Code
brew update && brew upgrade dart

Chocolatey (Windows)

Code
choco upgrade dart-sdk

asdf Version Manager (Cross‑platform)

Code
asdf plugin-add dart
asdf install dart latest
asdf global dart latest

After any of these commands, re‑run dart --version to confirm the new version.

Step 4 – Update Project Constraints

Open pubspec.yaml and adjust the SDK constraint if needed:

Code
environment:
  sdk: ">=3.3.0 <4.0.0"

Then fetch the updated packages:

Code
dart pub get

Step 5 – Verify Compatibility

Run the analyzer and tests to ensure nothing broke:

Code
dart analyze
dart test

If you encounter issues, the analyzer will point out deprecated APIs or required migration steps.

Step 6 – Upgrade CI/CD Pipelines

Most CI services provide a Dart or Flutter version selector. Below are examples for GitHub Actions and GitLab CI.

GitHub Actions

Code
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Flutter
        uses: subosito/flutter-action@v2
        with:
          channel: stable
          flutter-version: '3.22.0' # This pulls Dart 3.3.0
      - name: Install dependencies
        run: flutter pub get
      - name: Run tests
        run: flutter test

GitLab CI

Code
stages:
  - test

test:
  image: cirrusci/flutter:stable
  script:
    - flutter --version   # Shows bundled Dart version
    - flutter pub get
    - flutter test

Step 7 – Common Pitfalls & How to Fix Them

  • Version mismatch between Flutter and Dart: Always upgrade Flutter first; it guarantees a compatible Dart version.
  • Package constraints lock you to an older SDK: Update the environment.sdk range in pubspec.yaml and run dart pub upgrade --major-versions if needed.
  • CI caches old SDK binaries: Clear the cache or force a fresh install step in your pipeline configuration.

Conclusion

Upgrading the Dart SDK is straightforward when you follow a systematic approach: check the current version, upgrade via Flutter or a package manager, adjust project constraints, and verify everything works locally and in CI. By keeping the SDK current, you unlock new language features, improve performance, and stay secure.

Frequently Asked Questions

Do I need to upgrade Flutter when I upgrade the Dart SDK?

Flutter bundles a specific Dart version. Upgrading Flutter with <code>flutter upgrade</code> automatically upgrades the bundled Dart SDK to a compatible release. If you upgrade Dart separately, make sure the version satisfies Flutter's minimum SDK requirement, which you can find in the Flutter release notes.

Can I have multiple Dart SDK versions on the same machine?

Yes. Tools like <code>asdf</code>, <code>brew</code> (with separate prefixes), or Docker containers let you switch between versions. When using Flutter, the SDK version is tied to the Flutter installation, so you can keep a separate standalone Dart SDK for other projects.

My CI pipeline fails after upgrading Dart. What should I check first?

Start by clearing any cached SDK binaries and ensuring the CI configuration pulls the new version. Then run <code>dart analyze</code> and <code>dart test</code> locally with the same SDK to reproduce the failure. Common causes are outdated package constraints or breaking changes in the new language version.

Is it safe to upgrade the Dart SDK on a production server?

Generally, yes, but you should test the upgrade in a staging environment first. Verify that all packages compile, run your integration tests, and ensure the server's CI/CD pipeline uses the same SDK version before promoting the change to production.