Skip to content

Cannot find SDK when using dart run <package>@ or dart install. #63210

Open

Description

@jakemac53

This has been discussed in other channels but I wanted to open an issue on it for tracking purposes.

We have development related tools that need access to compilers and other artifacts from the SDK when running, specifically the MCP server, package:build_runner, package:webdev, and package:test to name a few.

These tools are not compatible with current AOT compilation mechanisms because the Platform.resolvedExecutable is just the path to the compiled AOT binary itself instead of something from the dart SDK. The well established historical pattern is to find the SDK using Platform.resolvedExecutable, as it actually gives you the exact SDK which was used to invoke the current script, and requires zero environment setup.

Note that we also have an API which relies on this in package:cli_util which doesn't work in this setup.

Previously discussed solutions

  • Find the SDK by looking up dart on PATH.
    • This only works if dart is on the users path at all, and also won't necessarily find the correct version of the SDK, just some version.
  • Use a DART_SDK environment variable
    • Only works if that variable is set, and won't necessarily find the correct version either.
  • Use a DART_SDK dart define variable (String.fromEnvironment).
    • Compilers would have to start reliably setting this (would affect many targets, and likely to be forgotten in new ones and be a long term source of pain).
    • Only points to the SDK at time of compilation, it may no longer exist there.

Proposed solution

Instead of compiling to a standalone executable, we could just compile the program without the AOT runtime, and then launch it using the runtime (via a shell script on the path for dart install).

This would also presumably result in smaller binaries and possibly faster compilation, but I haven't tested either of those.

Activity

  1. added
    area-dart-cliUse area-dart-cli for issues related to the 'dart' command like tool.
    dart-cli-runIssues related to 'dart run'
    on Apr 20, 2026
  2. jakemac53 commented on Apr 20, 2026

    @jakemac53
    ContributorAuthor
  3. bkonyi commented on Apr 20, 2026

    @bkonyi
    Contributor

    Slight clarification: Platform.executable and Platform.resolvedExecutable point to either dart or dartaotruntime if we're running from source or snapshot (we utilize this in the VM service to launch DDS). However, when running an AOT executable, it'll return the name of that executable since it has the dartaotruntime included in the binary.

    As for the proposed solution, if we don't compile to a standalone executable, the snapshots for all tools will need to be regenerated after each SDK upgrade since there's no stable ABI for AOT snapshots (which isn't much different than the situation we have with the AppJIT snapshots with pub global activate). Using self-contained executables has some nice properties (e.g., we don't have to worry about recompiling between SDK versions, no chance of existing tools breaking after updates, etc.), but obviously this is a pain point.

    I wonder if, at least for dart install, we can do something special to report these paths properly. We control how these executables are generated, the location of the SDK is used to generate them, and where they're going to be installed. I think we can make an assumption that these executables are going to remain on the user's disk and their Dart SDK won't move. In that case, if we provide an option to specify the SDK root to dart compile exe (or whatever codepath dart install is taking to compile), we can include it in the compilation as a Dart environment variable (e.g., dart.sdk) and use that to determine the paths returned from Platform.executable / Platform.resolvedExecutable.

  4. jakemac53 commented on Apr 20, 2026

    @jakemac53
    ContributorAuthor

    It is definitely true that you have to recompile for newer SDKs, but changing SDKs is not a super common task and pub global activate already handled this quite transparently, it just costs you a few seconds of time on the first invocation of the tool after changing SDKs.

    I think we can make an assumption that these executables are going to remain on the user's disk and their Dart SDK won't move.

    You can always just re-install if you did for some reason move it as well, ideally we would have a nice error message indicating this resolution for the issue, probably just in package:cli_util

  5. jakemac53 commented on Apr 20, 2026

    @jakemac53
    ContributorAuthor

    use that to determine the paths returned from Platform.executable / Platform.resolvedExecutable.

    I don't think we want to change the behavior of these APIs. It was always a bit of a hack how they were being used, it just happened to work reliably until AOT and so we never did a different solution.

    I think the API I linked above in package:cli_util is probably where we should put any logic. And then migrate all the tools to use that instead of the simple "two directories above Platform.resolvedExecutable" solution they do today.

  6. bkonyi commented on Apr 20, 2026

    @bkonyi
    Contributor

    If this was only going to impact our own tooling, I'd agree that package:cli_util is the right place for this sort of logic. However, for dart install, there's going to be other tools that use these values that will have the same issues we are, so a more general approach would reduce confusion and not require tool authors to implement this fix to be compatible with dart install.

    We already fudge these paths in the VM now that dart is actually a precompiled dartdev executable that forks out to dartvm: https://github.com/dart-lang/sdk/blob/main/runtime/bin/dartdev.cc#L519

  7. dcharkes commented on Apr 21, 2026

    @dcharkes
    Contributor

    Trying to zoom out from implementation details and to expectations based on public CLI:

    • dart run ... (no @). You need a current project with resolved pubspec.yaml/package_config.json. Both your dependencies and the Dart SDK are locked. And you have access to your own sources.
    • dart install places an executable on PATH. You run the executable with my_executable. Neither your dependencies nor your Dart SDK are locked. You have no access to your own sources.
    • dart run ...@ you are using a dart, so it would be weird if your Dart SDK isn't "selected". The question is what does a selected Dart SDK mean? (And yes/no access to your own sources?)

    What does a "selected" Dart SKD mean:

    1. Availability of a dart.exe path in your Dart program. Probably yes: It's better than getting a dart via PATH.
    2. Guarantee that the executable that's running is a dart.exe or dartaotruntime.exe or dartaotruntime.exe+aotsnapshot of that Dart SDK. Maybe no: If you don't know if its AOT or JIT you can't possibly load spawnUri, load a kernel snapshot or load an AOT snapshot. Unless we specify the run mode of dart run ...@.

    Now, we do don't do (2), only (1). Then package:test would need to dart compile kernel with that supplied Dart and then dart run with that kernel snapshot. I believe right now, package:test does Isolate.spawnUri with the kernel snapshot.

    But even if we would do (2), if you don't know if you are running in a dart.exe or dartaotruntime.exe you don't know if you can spawn a kernel snapshot. So, then you'd

    Do we want to lock down the run mode of dart run ...@?
    Actually, do we want to lock down the run mode of dart run ... (non @) ? (#60896 It would make consecutive runs of FFIgen for example quite a bit faster).

    • Basically both dart run and dart pub global run were JIT, and people started relying on that.

    Dart apps can be written based on assumptions:

    1. No assumptions, no use of Platform.executable, no use of packageConfig. App will run in any mode.
    2. Needs a dart.exe and the rest of the Dart SDK. But that doesn't have to collaborate with how the current app is working. -> a dart on PATH would be enough.
    3. Needs to be run in JIT mode, because it tries to spawn kernel snapshots that it compiled with this dart.
    4. Needs to be run in AOT mode, because it tries to spawn AOT snapshots that it compiled with this Dart SDK version.
    5. Needs to have access to a packageConfig because it tries to access source files from its own package.
      If we were to specify it in the pubspec, it would be something along the lines of
    runtime-requirements:
      sdk: not-needed | needed | locked # locked is for if you want to load snapshots into
      jit-supported: true | false
      aot-supported: true | false # If only AOT is supported it's because you're relying on compiling AOT snapshots, quite uncommon though.
      source-access: true | false # Whether you need access to your own sources

    The current access via Platform.resolvedExecutable and Platform.packageConfig hide these various axes of runtime requirements.

    Exposing Platform.resolvedExecutable is not the same as promising that you're running in JIT.

    I think we either need to start specifying the runtime requirements of packages correctly, and chose the runtime mode based on that (and then we can do the same for dart run non-@). Or, we give up on dart run ...@ using AOT and implement dart pub global run semantics promising we always run in JIT.

    (Running in AOT is much faster if you do multiple runs for tools, such as FFIgen or test.)

    cc @sigurdm @jonasfj You wanted badly to get rid of the the logic in dart pub global.


    I wonder if, at least for dart install, we can do something special to report these paths properly.

    None of my above reasoning applies to dart install. I believe dart install should create a black-box executable that knows nothing about the Dart SDK it was installed with. Similar to other package managers which might actually precompile binaries and upload them to a server, and you'd download the precompiled binaries. The confusion for dart install is that we don't have a split between package manager and compiler like you have in Rust with rustc and cargo.

  8. jakemac53 commented on Apr 21, 2026

    @jakemac53
    ContributorAuthor

    Yes, I agree some configuration for how you want to be compiled would be ideal here.

    • dart install places an executable on PATH. You run the executable with my_executable. Neither your dependencies nor your Dart SDK are locked. You have no access to your own sources.

    Why should this not have access to its own sources? I agree this is the behavior, but I don't think that there is any benefit, it's just a consequence of the implementation. And since we don't have any functionality yet afaik to bundle assets with the binary, it leaves a large category of apps hanging out to dry with no solution at all.

  9. dcharkes commented on Apr 21, 2026

    @dcharkes
    Contributor

    Why should this not have access to its own sources? I agree this is the behavior, but I don't think that there is any benefit, it's just a consequence of the implementation.

    Because committing to that capability will then mean all the sources are basically bundled as assets. I'd rather make an actual asset API for Dart data assets than have it as a side effect via the pub cache. Besides, the pub cache now GCs, so we must actually copy all sources. That means coming up with a new package_config.json with all transitive packages that are copied into your app bundle as assets.

    And since we don't have any functionality yet afaik to bundle assets with the binary, it leaves a large category of apps hanging out to dry with no solution at all.

    I agree we should not remove dart pub global run before we create a solution. We should add support for Dart data assets (#54003).

  10. jakemac53 commented on Apr 21, 2026

    @jakemac53
    ContributorAuthor

    Besides, the pub cache now GCs

    We could also make it not GC globally activated/installed packages dependencies?

  11. jakemac53 commented on Apr 21, 2026

    @jakemac53
    ContributorAuthor

    I agree we should not remove dart pub global run before we create a solution. We should add support for Dart data assets (#54003).

    The problem is that we are launching these now, and it's going to create a very confused story if our own tools cannot be used. This issue is 3 years old with no update for over a year. Are we actually working on it?

  12. sigurdm commented on Apr 23, 2026

    @sigurdm
    Contributor

    Besides, the pub cache now GCs, so we must actually copy all sources.

    • The gc is manually activated
    • The gc should be smart enough to not remove used packages if the package_config referring to them still exists. If the resolution is made in a temp directory and then moved this might not work. We should look at that.
  13. jonasfj commented on Apr 29, 2026

    @jonasfj
    Member

    Do we want to lock down the run mode of dart run ...@?

    It doesn't matter much, people will write tools that depends on current behavior.
    Whenever we change behavior, we'll have to balance that with how many things we break.

    We could document that we discourage Isolate.spawnUri, and recommend Isolate.spawn or subprocesses instead.


    Going back to the root of this issue.

    How to find Dart SDK from dart run?

    Proposal: dart foo.dart, dart run foo dart run foo@, dart test will supply environment variables:

    • DART_ROOT, pointing to the root folder of the Dart SDK (the folder that contains bin/dart).
    • FLUTTER_ROOT, pointing to the root folder of the Flutter SDK -- FLUTTER_ROOT is already established in shared.sh/.bat in flutter wrapper script today.

    To support this we create a findDartSdk() function (and findFlutterSdk()):

    • Published in package:cli_util (or a new package:find_dart)
    • Searches in order of priority:
      • DART_ROOT,
      • Platform.resolvedExecutable,
      • Dart SDK relative to FLUTTER_ROOT,
      • dart from PATH,
      • Dart SDK relative to flutter from PATH,
      • throw SdkUnresolvedException('Please set $DART_ROOT or add dart to $PATH')
    • At each location, we:
      • File.statSync to see if bin/dart exists.
      • Maybe other sanity checks, but probably not (could be looking for version file).

    To hold ourselves to this promise going forward we document DART_ROOT in:

    As these are the likely places you'll want to have it. But obviously, we should probably set/propagate the DART_ROOT / FLUTTER_ROOT envs var whenever the opportunity arises.

    We should also consider updating documentation Platform.resolvedExecutable to mention that the better to use findDartSdk. And consider deprecating Platform.resolvedExecutable.


  14. dcharkes commented on Apr 29, 2026

    @dcharkes
    Contributor

    To add to the notes that @jonasfj wrote of our discussion with @sigurdm:

    • Platform.resolvedExecutable, Isolate.packageConfig, and friends are leaky abstractions. They leak the run mode. We suspect 95% of all use cases can be solved without relying on those leaks. E.g. by DART_ROOT, by spawning a process instead of an isolate group, by data assets instead of by locating source files. The goal should be for package authors to write their code that does not rely on leaky abstractions.
    • DART_ROOT in Flutter should not point to the flutter/bin but to the nested dart-sdk/bin.
    • The implementation of DART_ROOT in dartdev should work in Flutter and if Dart is invoked in weird ways through symlinks or PATHEXT on Windows.
  15. 1 remaining item

  16. jakemac53 commented on Apr 29, 2026

    @jakemac53
    ContributorAuthor

    I am generally on board with the environment variable plan for fixing the SDK finding issue.

    It does not fully resolve the dart install case, so I think there is still an issue there, but one solution is that the tools just require users to set these variables manually, or try to use something like which dart etc (but remember most of our users are on windows so we will need to also have a solution there).

  17. jonasfj commented on Apr 29, 2026

    @jonasfj
    Member

    The dart install case I why I proposed falling back to:

    • dart from PATH,

    and finally:

    • throw SdkUnresolvedException('Please set $DART_ROOT or add dart to $PATH')

    because then the user will get a message they can easily fix.

    Either throw dart on path or define DART_ROOT.


    I don't think it's unreasonable to expect that the dart version you want to use is available on PATH -- but I'm also sure that for some users it won't be today.

  18. jakemac53 commented on Apr 29, 2026

    @jakemac53
    ContributorAuthor

    It is also worth noting that if something depends on the SDK, it also probably only works with certain versions of the SDK.

    The dart pub global activate path solved for this afaik, because if the SDK changed it would do a new solve and compile. This is actually the desired behavior in this case. For webdev, it has no design constraint or goal around being a standalone executable, it just wants to be an executable available on your PATH, that is compatible with your current dart/flutter SDK.

  19. bkonyi commented on Apr 29, 2026

    @bkonyi
    Contributor

    I was looking into another issue which we wanted to set some environment variables for, so I've pulled together this change to set DART_ROOT from dartdev to act as a proof of concept for now: https://dart-review.googlesource.com/c/sdk/+/499300.

    This only works when we actually run the dartdev isolate (e.g., dart run foo.dart, not dart foo.dart), but that can easily be fixed.

  20. natebosch commented on Apr 29, 2026

    @natebosch
    Member

    We should also consider updating documentation Platform.resolvedExecutable to mention that the better to use findDartSdk. And consider deprecating Platform.resolvedExecutable.

    If we want to point official docs towards any implementation of findDartSdk we should strongly consider implementing it in a packaged published by our core publisher.

  21. mit-mit commented on Jul 14, 2026

    @mit-mit
    Member

    Was this resolved? I guess this blocks dart-lang/webdev#2847 ?

    cc @kevmoo

  22. dcharkes commented on Jul 14, 2026

    @dcharkes
    Contributor

    dart run webdev@ can rely on DART_ROOT because it's set via dartdev since c5a5742.

    With dart install webdev there is no link to the Dart SDK it was installed with. In case dart is on PATH webdev could use that, or if the developer has set DART_ROOT in their system environment variables, that can be used.

    Also, why don't people do dart run webdev and have webdev as a dev dependency? (dart-lang/webdev#2847 (comment))

    If we want to point official docs towards any implementation of findDartSdk we should strongly consider implementing it in a packaged published by our core publisher.

    This has not happened afaik.

    It is also worth noting that if something depends on the SDK, it also probably only works with certain versions of the SDK.

    dart installed things should not depend on the SDK version. I don't know if webdev depends on internal SDK details. If it does, we should make it only depend on public API (e.g. dart <...>) and promise to not break those.

  23. jakemac53 commented on Jul 14, 2026

    @jakemac53
    ContributorAuthor

    dart installed things should not depend on the SDK version. I don't know if webdev depends on internal SDK details. If it does, we should make it only depend on public API (e.g. dart <...>) and promise to not break those.

    It depends on the VM service which while fairly stable I think can have breaking changes....

  24. bkonyi commented on Jul 14, 2026

    @bkonyi
    Contributor

    It depends on the VM service which while fairly stable I think can have breaking changes....

    Errrr, it's a bit of a weird situation since it depends on DWDS (which currently isn't part of the SDK, but will be soonish) and DDC, which is an internal SDK artifact.

    FWIW, I really want to move all of our web stack into the SDK in the next year or so. Having Pub vended tooling depend on SDK internal details is a huge headache.

  25. jakemac53 commented on Jul 14, 2026

    @jakemac53
    ContributorAuthor

    which currently isn't part of the SDK, but will be soonish

    It will only be developed in the SDK right? Webdev will still have to depend on it as a pub package, so I don't think it helps to have it developed there (other than it may more eagerly surface breaking changes to the VM service).

    One solution is moving webdev into the SDK as well... but I would honestly consider a rewrite if that was the case (to use frontend server and not build_web_compilers).

  26. bkonyi commented on Jul 14, 2026

    @bkonyi
    Contributor

    which currently isn't part of the SDK, but will be soonish

    It will only be developed in the SDK right? Webdev will still have to depend on it as a pub package, so I don't think it helps to have it developed there (other than it may more eagerly surface breaking changes to the VM service).

    Nope. The plan is that it will eventually become part of the Dart CLI, similar to how DDS is now shipped as dart development-service instead of package:dds. We want to move away from shipping core parts of our stack that depend on SDK internals via pub.

    One solution is moving webdev into the SDK as well... but I would honestly consider a rewrite if that was the case (to use frontend server and not build_web_compilers).

    That's probably what's going to have to happen since we encountered significant resistance to moving webdev into the SDK due to our dependency on build_runner.

  27. jakemac53 commented on Jul 14, 2026

    @jakemac53
    ContributorAuthor

    That's probably what's going to have to happen since we encountered significant resistance to moving webdev into the SDK due to our dependency on build_runner.

    The only public dependency is on build_daemon... which IIRC is really just handling the client side of the build daemon protocol. The dev dependencies really should not matter here... they aren't shipped to users. So I think we could/should definitely push back on this, to allow build_runner as a dev dependency. Especially given that we do not have any equivalent codegen solution provided by the SDK.

  28. kevmoo commented on Aug 9, 2026

    @kevmoo
    Member

    We've opened a concrete implementation proposal on package:cli_util to address this across the ecosystem: dart-lang/tools#2504.

    Publishing this in package:cli_util allows us to roll out the fix immediately on Pub and unblock tools (webdev, coverage, benchmark_harness, etc.) across existing and upcoming Dart versions without gating on a specific SDK release.

    Key aspects of the proposal:

    • Multi-tier SDK discovery (sdkPath / findSdkPath()):
      1. Platform.resolvedExecutable (valid SDK check preserving JIT hermeticity and protecting against stale env vars).
      2. DART_SDK environment variable override.
      3. System PATH traversal (supporting Windows PATHEXT and Flutter's bin/cache/dart-sdk wrapper structure).
      4. FLUTTER_ROOT fallback.
    • dartExecutable helper: Returns the resolved path to the real dart binary to eliminate recursive self-invocation loops when AOT binaries spawn child processes.
    • Zero-dependency footprint: Implemented using pure dart:io and package:path to keep cli_util lightweight.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area-dart-cliUse area-dart-cli for issues related to the 'dart' command like tool.dart-cli-runIssues related to 'dart run'

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions