`rustup +nightly run cargo` seems like it could work but doesn't

[epage]

Verification

• I searched for recent similar issues at https://github.com/rust-lang/rustup/issues?q=is%3Aissue and found no duplicates.
• I am on the latest version of Rustup according to https://github.com/rust-lang/rustup/tags and am still able to reproduce my issue.

Problem

In rust-lang/cargo#16149 a user was trying to figure out how to do rustup run with nightly and tried:

$ rustup +nightly run cargo miri test
error: toolchain 'cargo' is not installed

From the user:

... etc. I found many mentions of cargo +toolchain on the net, but it was really quite hard to find the syntax to actually get this to run. One reason is that as a beginner I really had no idea if I was looking for an option to run, not rustup or cargo..

Made worse by the fact that rustup accepts a toolchain parameter like cargo does

Steps

1. Run rustup +nightly run cargo -h

Possible Solution(s)

Option 1: Improve the diagnostic by checking if the toolchain name is a command and suggesting:

• rustup run nightly cargo -h (if they specified a toolchain)
• rustup run <default> cargo -h (if they didn't specify a toolchain)

Option 2: Hack up the command-line in such a way as to make this work

Notes

No response

Rustup version

rustup 1.28.2 (e4f3ad6f8 2025-04-28)

Installed toolchains

Default host: x86_64-unknown-linux-gnu
rustup home:  /home/epage/.rustup

installed toolchains
--------------------
stable-x86_64-unknown-linux-gnu (active, default)
beta-x86_64-unknown-linux-gnu
nightly-x86_64-unknown-linux-gnu
nightly-2023-11-13-x86_64-unknown-linux-gnu
nightly-2024-06-03-x86_64-unknown-linux-gnu
nightly-2024-09-10-x86_64-unknown-linux-gnu
nightly-2024-10-19-x86_64-unknown-linux-gnu
nightly-2025-01-27-x86_64-unknown-linux-gnu
nightly-2025-04-02-x86_64-unknown-linux-gnu
nightly-2025-06-26-x86_64-unknown-linux-gnu
1.0.0-x86_64-unknown-linux-gnu
1.48-x86_64-unknown-linux-gnu
1.48.0-x86_64-unknown-linux-gnu
1.56.0-x86_64-unknown-linux-gnu
1.57.0-x86_64-unknown-linux-gnu
1.58.0-x86_64-unknown-linux-gnu
1.60.0-x86_64-unknown-linux-gnu
1.64-x86_64-unknown-linux-gnu
1.64.0-x86_64-unknown-linux-gnu
1.65-x86_64-unknown-linux-gnu
1.65.0-x86_64-unknown-linux-gnu
1.66-x86_64-unknown-linux-gnu
1.66.0-x86_64-unknown-linux-gnu
1.70-x86_64-unknown-linux-gnu
1.70.0-x86_64-unknown-linux-gnu
1.71-x86_64-unknown-linux-gnu
1.71.0-x86_64-unknown-linux-gnu
1.71.1-x86_64-unknown-linux-gnu
1.72-x86_64-unknown-linux-gnu
1.74-x86_64-unknown-linux-gnu
1.75-x86_64-unknown-linux-gnu
1.76-x86_64-unknown-linux-gnu
1.80-x86_64-unknown-linux-gnu
1.80.1-x86_64-unknown-linux-gnu
1.81-x86_64-unknown-linux-gnu
1.83-x86_64-unknown-linux-gnu
1.83.0-x86_64-unknown-linux-gnu
1.84-x86_64-unknown-linux-gnu
1.85-x86_64-unknown-linux-gnu
1.86-x86_64-unknown-linux-gnu
1.86.0-x86_64-unknown-linux-gnu
1.88-x86_64-unknown-linux-gnu
1.89-x86_64-unknown-linux-gnu
1.90-x86_64-unknown-linux-gnu
stage1

active toolchain
----------------
name: stable-x86_64-unknown-linux-gnu
active because: it's the default toolchain
installed targets:
  aarch64-apple-darwin
  i686-unknown-linux-gnu
  i686-unknown-linux-musl
  powerpc-unknown-linux-gnu
  wasm32-unknown-unknown
  x86_64-pc-windows-gnu
  x86_64-pc-windows-msvc
  x86_64-unknown-linux-gnu
  x86_64-unknown-linux-musl
  x86_64-unknown-none

OS version

Linux dross 6.16.3-76061603-generic #202508231538~1758561135~22.04~171c8de SMP PREEMPT_DYNAMIC Mon S x86_64 x86_64 x86
_64 GNU/Linux

[rami3l]

@epage I think it's hard to explain that +toolchain is a rustup feature rather than a cargo one; I didn't know that before taking the responsibility here.

The original help message:

help: invoke `cargo` through `rustup` to handle `+toolchain` directives

... is technically correct but only makes sense once you are aware of this fact, so I suggest the following actions:

1. Detect +toolchain in rustup run and issue a warning. I think that's better than your proposal 1.

2. Add/improve a section in the rustup user guide to explain that more in detail and make the above message point to it.

If you agree, I think we can work in parallel to address these points in the respective repos.

Bonus: there indeed have been discussions about using a default toolchain explicitly, and since rustup run is IIRC mostly used to invoke a non-proxied binary it might be helpful in this case as well, but we have to come up with something that feels natural and coherent with the current scheme.

[epage]

I think I'm not quite picturing your recommendation right and would be interested in more detail.

I'm also not sure what the relevance is of the cargo error. That issue is more framing for a user trying to use rustup run and getting confused by it not quite behaving like other parts of rustup (and users easily overlooking --help when trying something).

[rami3l]

@epage So I'm trying to think from @sliedes' perspective here:

• They've got the following hint; that's a good sign but they're not sure what "invoke cargo through rustup" means...

  help: invoke `cargo` through `rustup` to handle `+toolchain` directives

  • The trap here is that we know cargo +toolchain is calling rustup but the same is not necessarily true for the user.
  • Here an additional line could help: see <link> from the rustup book for more info, where we explain the two approaches of invoking cargo through rustup above.

• If after rustup --help or whatever they choose to do rustup run, then we suggest the right syntax for them:

  > rustup +nightly run cargo miri test
  warning: toolchain override '+nightly' is a no-op in `rustup run cargo`
  warning: the toolchain named 'cargo' will be used for the command
  hint: maybe try `rustup run nightly cargo` instead?
  error: toolchain 'cargo' is not installed

Please feel free to correct me if you've found anything inappropriate here.

[djc]

Why couldn't we just make rustup +nightly run cargo miri test do the right thing?

[rami3l]

Why couldn't we just make rustup +nightly run cargo miri test do the right thing?

@djc I agree that a redesigned rustup run command shouldn't take the toolchain name as the first argument; however rustup +nightly is an afterthought here so the syntax somehow has to feel unnatural here until we break stuff.

What is making me puzzled right now is this: it could be argued that we should support both, but in that case which version should take the precedence and, more importantly, what should the clap help look like? Relying on some implicit fallback mechanism here is making our argparser less predictable I think.

What would the semantics be then?

PS: We could take the classical path and introduce an alternative command like rustup exec that is the "correct" version of rustup run (say rustup +nightly exec cargo --help), and then deprecate the latter and hide it from the docs.

[djc]

What is making me puzzled right now is this: it could be argued that we should support both, but in that case which version should take the precedence and, more importantly, what should the clap help look like? Relying on some implicit fallback mechanism here is making our argparser less predictable I think.

We could just error if both are specified and inconsistent.

[epage]

They've got the following hint; that's a good sign but they're not sure what "invoke cargo through rustup" means...

Here an additional line could help: see from the rustup book for more info, where we explain the two approaches of invoking cargo through rustup above.

Ok, so the comment about the rustup book is related to the cargo side of this.

Should that instead be posted over at rust-lang/cargo#16149? I think the inclusion of a discussion on the Cargo side was partly what was confusing me.

If after rustup --help or whatever they choose to do rustup run, then we suggest the right syntax for them:

Yes, this is similar to what my Option 1.

I'd instead recommend

> rustup +nightly run cargo miri test
warning: toolchain override '+nightly' is ignored in `rustup run cargo`
error: toolchain 'cargo' is not installed
note: the first parameter to `rustup run` is a toolchain
help: to run using `+nightly`, try `rustup run nightly cargo`

or if you used annotate-snippets (which cargo is moving to)

> rustup +nightly run cargo miri test
warning: toolchain override '+nightly' is ignored in `rustup run cargo`
error: toolchain 'cargo' is not installed
  |
  = note: the first parameter to `rustup run` is a toolchain
  = help: to run using `+nightly`, try `rustup run nightly cargo`

• Unsure what the second warning was about
• Put the hint after the associated error and renamed it to help to match rustc
• Re-framed it from being a question to match https://rustc-dev-guide.rust-lang.org/diagnostics.html#suggestion-style-guide (something we've been fixing in Cargo over time)