PSA: Rust documentation is now optional and opt-in when installing via rustup

As of the most recent Rust nightly rustup no longer installs documentation by default. If you already have docs installed then future toolchain upgrades will keep them installed, but fresh installs will not receive docs. We've done this because the docs have significant download size and are not critical for most developers to possess locally.

If you do want docs for your active toolchain you can run:

rustup component add rust-docs

To remove docs from your existing, updated, nightly install, run:

rustup component remove rust-docs

Is this the default for all toolchains? I tend to imagine we should have docs installed for stable toolchains, though I get why not doing it for nightly might be OK. (Though even then I’d probably prefer it to detect if it’s in interactive mode and ask the user whether or not to install docs if it is.)

1 Like

Is there a global switch to change that? I can understand the reasoning, but I'm in the other group that often travels :).

1 Like

I am strongly against not installing by default. Obviously, when you need offline documentation, you can't download it!

The other day my internet has gone down, but I've managed to have a nice evening because I thought: "Hey, I can write a B-tree! But is there documentation for Rust somewhere in ~/.multirust/toolchains?". I was very pleased when I did found the docs. It would not had occurred to me that I might want to download docs manually just in case.


I'm also against the decision, at least for the stable branch. I teach people to rely on 'rustup doc'. But you could print a big note after installation that the docs are missing and how to add them.


Thanks for the feedback. I'll consider that maybe docs should be optional, but opt-out. I also use the docs offline while I'm traveling. But we also get a lot of feedback that Rust downloads are too big.

Whether they are installed by default or not, it seems like component selection should be part of the install process.

Another consideration is that right now there is no way to define optional, opt-out, components. It will take more work in various places to make that possible.


Maybe some like rustup install stable with docs for it to be a one liner.

Also it would be a NTH that rustup update does print from what to what are you updating

rustup update
info: syncing channel updates for 'stable-x86_64-pc-windows-msvc'
info: downloading component 'rustc'
 26.7 MiB /  26.7 MiB (100 %)   1.2 MiB/s ETA:   0 s
info: downloading component 'rust-std'
 33.5 MiB /  33.5 MiB (100 %)   1.2 MiB/s ETA:   0 s
info: downloading component 'rust-docs'
  6.7 MiB /   6.7 MiB (100 %)   1.2 MiB/s ETA:   0 s
info: downloading component 'cargo'
  2.5 MiB /   2.5 MiB (100 %)   1.2 MiB/s ETA:   0 s

6.7MiB is only 9.2% of the total.

1 Like

We could extract it on the first "rustup docs" call.


I can confirm. On a network drive extracting the docs alone takes 20 minutes!


Would much much rather opt-out. I'm probably not going to bother opting in, and I'm probably going to regret it at some point. If I the docs annoyed me, I'd cancel and figure out how to opt out.

1 Like

I did put the numbers because the OP said this docs have significant download size rustc and rustlib have significant download size, not the docs... thought

Thought having SSD that means almost nothing ;)...

N1, I was thinking in downloading them as md files (the download size would be less than HTML I think) then converting them to html would be best in this call, thought with the current HTML download perhaps it is not possible.

Maybe when installing, updating or something, there could be a message you have this opt-in and opt out features: doc.

So the people know that there are or are not docs installed. (Well, for starters, I didnt even know I did have the docs installed or that I can access them trought that command).

Another thing I will like to know if there is no doc installed, what will do rustup doc do?

+1 for a way to have docs automatically installed. I'll never remember to install the docs until I need them, by which point it will be too late.

I personally think that it's a pretty neat feature for Rust to have the specific docs for the version of rust you're using just a rustup doc away. I understand that some/many people may not need them, but a permanent opt-in for getting docs would be very useful.

I'd very strongly prefer for docs to be installed by default but with an opt out. They're so incredibly useful, especially when you don't have internet (at which point if you forgot to install them, then you're screwed).

I'm happy to help with that, is there an issue or RFC that defines the ideal work flow?

I'd like it to present options while downloading/installing the required components.

  • If I haven't opted out by the time that's done, install docs.
  • Leave options for rust-src and racer/RLS on the screen
  • Command line options for automated installs.

Also remember that cargo registry will take more space that the install and you will not have a chance to opt in or out of that AFAIK (I for example dont know how much space it has right now on my SSD).

I don't mind having one copy of the docs, but having a separate copy for each of stable, beta and nightly is too much. Nightlies are updated frequently, so their docs also use most bandwidth.

Maybe install stable docs by default, and beta/nightly as opt-in?


I'd like to register my support for "optional, opt-in" docs. Over the past few weeks I've been intensely annoyed by both the install times and disk usage.

I think a happy medium could be to download the compressed docs, and only decompress them on rustup component add rust-docs. This is kind of a best-of-both-worlds scenario: the main argument against opt-in appears to be that you usually want to opt in at times you don't have an internet connection, but here you wouldn't need one.

(Also: currently, rustup fails on my machine on the installing rust-docs step. How can I access a version of rustup that has this change?)


This last suggestion is exactly what I was going to suggest on bumping into the thread: always download, but don't uncompress unless explicitly requested. That way if you need them and are offline, you can still get them. (Probably needs to be documented in rustup in a helpful way.)


Unless I'm mistaken, due to the opt-in change, rustup doc fail without any error message when the doc isn't installed. Wouldn't it be more user friendly to show a message like this?

The documentation is not currently installed; you can install it by running rustup component add rust-docs.


@tcf Yes, that would be better.

The point that docs are a only small part of the download time is well taken.

I'm still undecided about what to do here but it seems like it's going to be a combination of multiple things. Here's what I'm inclined to do:

Thanks for your patience.

1 Like