The flutter tool
flutter command-line tool is how developers (or IDEs on behalf of developers) interact
flutter --help lists the developer-facing commands that
flutter --help --verbose lists all the commands that
flutter supports, in particular, it also lists the
features that are of use to Flutter contributors.
flutter update-packages, which downloads all the Dart dependencies for all Dart packages in the Flutter repository.
flutter analyze --flutter-repo, as described on Using the Dart analyzer.
When contributing to Flutter, use
git pull --rebase or
git rebase upstream/master
flutter tool itself is built when you run
flutter for the first time and each time
git pull --rebase (or
flutter upgrade, or anything that changes the current commit).
Markdown documentation can be found for some commands in flutter/packages/flutter_tools/doc/.
Making changes to the
If you want to alter and re-test the tool's behavior itself, locally commit your tool change
in git and the tool will be rebuilt from Dart sources in
packages/flutter_tools the next
time you run
flutter. Alternatively, delete the
Doing so will force a rebuild of the tool from your local sources the next time you run
flutter_tools tests run inside the Dart command line VM rather than in the
flutter shell. To run the tests, navigate to
packages/flutter_tools and run:
../../bin/cache/dart-sdk/bin/pub run test
The pre-built flutter tool runs in release mode with the observatory off by default.
To enable debugging mode and the observatory on the
flutter tool, uncomment the
FLUTTER_TOOL_ARGS line in the
bin/flutter shell script.
flutter command-line tool
Developers are expected to run flutter command without knowing too much details about the
flutter command. However, there are some cases in which you may find it useful to debug
flutter command especially when it's difficult to reproduce your issue.
flutter command is just a wrapper and it will finally run
$FLUTTER_ROOT/bin/cache/flutter_tools.snapshot generated by flutter_tools package.
That's to say, you can debug
flutter command as a Dart Command Line App.
flutter doctor -vv as an example. You can debug it following steps below:
a. Open the flutter_tools package in Android Studio
b. Create a new Dart Command Line App by
Add Configurations and configure it as below:
The Dart file refers to bin/flutter_tools.dart where the main function is located. Program arguments refers to the arguments for flutter command, it's passed to main method directly. Working directory is which flutter project you want to run the flutter command, and is not always necessary.
c. The dart sdk is used to run the bin/flutter_tools.dart and expected to configure as below:
d. If you make some changes to the flutter_tools package, you may need to do as 'Making changes to the
flutter tool' says above because flutter command might be triggered implicitly by gradle, etc.
Though those steps given above are under Android Studio, the logic also works for other IDEs.
Adding, removing, or making changes to Dart dependencies
Once you've edited a
pubspec.yaml file in the Flutter repository to change a package's dependencies,
flutter update-packages --force-upgrade to resynchronize all the
This does a full cross-package version solve for the entire repository.
If you need to pin a particular version, edit the table at the top of the
Using a locally-built engine with the
To allow the tool to be used with a locally-built engine, the
flutter tool accepts two
local-engine-src-path, which specifies the path to your engine repository,
local-engine, which specifies which build of the engine to use.
A typical invocation would be:
--local-engine-src-path /path/to/engine/src --local-engine=android_debug_unopt.
If your engine is in a directory called
engine that is a peer to the framework repository's
flutter directory, then you can omit
--local-engine-src-path and only specify
You can also set the environment variable
$FLUTTER_ENGINE instead of specifying
--local-engine should specify the build of the engine to use, e.g. a profile build for Android, a debug build for Android, or whatever. It must match the other arguments provided to the tool, e.g. don't use the
android_debug_unopt build when you specify
--release, since the Debug build expects to compile and run Dart code in a JIT environment, while
--release implies a Release build which uses AOT compilation.
Additionally if you've modified the Dart sources in your engine,
you will need to add a
dependency_overrides section to point to your
package:sky_services to the
pubspec.yaml for the flutter app you're using the custom engine
with. A typical example would be:
dependency_overrides: sky_engine: path: /path/to/flutter/engine/out/host_debug/gen/dart-pkg/sky_engine sky_services: path: /path/to/flutter/engine/out/host_debug/gen/dart-pkg/sky_services
host_debug with the actual build that you want to use (similar to
--local-engine, but typically
a host build rather than a device build).
If you do this, you can omit
--local-engine-src-path and not bother to set
flutter tool will use these paths to determine the engine also! The tool tries really hard to
figure out where your local build of the engine is if you specify
Adding dependencies to the Flutter Tool
Each dependency we add to Flutter and the Flutter Tool makes the repo more difficult to update and requires additional work from our clients to update.
Only packages which are developed by the Dart and/or Flutter teams should be permitted into the Flutter Tool. Any third party package that is currently in use is grandfathered in, but their versions must be pinned in update_packages.dart . These packages should only be updated after a human review of the new version. If a Dart and/or Flutter team package depends transitively on an un-maintained or unknown package, we should work with the owners to remove or replace that transitive dependency.
Instead of adding a new package, ask yourself the following questions:
- Does the functionality already exist in the SDK or an already depended on package?
- Could I develop the same functionality myself in a few hours of work?
- Is the package actively developed and maintained by a trusted party?