← Back to Blog
·
Flutter

Cheatsheet: Commit or not commit pubspec.lock file

When should you commit the pubspec.lock file in Flutter projects? A definitive guide.

The pubspec.lock file is a crucial part of Flutter/Dart dependency management. It locks all your project’s dependencies to specific versions, ensuring that everyone working on the project gets exactly the same versions of packages. This file is automatically generated when you run flutter pub get or dart pub get.

The Cheatsheet

1. Monolith Application Package

Commit pubspec.lock

When you have a single Flutter application with all code in one module, you should commit the pubspec.lock file. This ensures that all developers and CI/CD pipelines use the exact same package versions.

2. Multimodule Application Package

Commit all pubspec.lock files

For applications with multiple modules (e.g., feature modules, shared modules), you should commit the pubspec.lock file in:

  • The root project
  • Each module directory

This maintains version consistency across all modules and prevents version conflicts.

3. Library Package

Ignore pubspec.lock in root, Commit pubspec.lock in example module

For Flutter/Dart packages that will be published to pub.dev:

  • Do NOT commit the root pubspec.lock
  • DO commit the pubspec.lock in the example module

Benefits of Following These Rules

1. Build Consistency

By committing the appropriate pubspec.lock files, you ensure that:

  • All developers use the same package versions
  • CI/CD builds are reproducible
  • No unexpected behavior due to different package versions

2. Faster CI Builds

When you commit pubspec.lock:

  • CI machines can use cached packages
  • flutter pub get runs faster
  • Build times are reduced

3. Library Package Flexibility

Not committing pubspec.lock in library packages:

  • Allows the library to support a range of compatible versions
  • Makes the library more flexible for users
  • Prevents locking to specific versions that might be too restrictive

Best Practices

  1. Always review pubspec.lock changes in pull requests
  2. Keep your dependencies up to date
  3. Use version constraints in pubspec.yaml that are not too restrictive
  4. Document your dependency management strategy in your project’s README

Remember, the goal is to balance between build consistency and flexibility, depending on your project type. Following these guidelines will help you maintain a healthy and efficient Flutter project.