dox4/rustup
1
0
Fork 0
mirror of https://github.com/rust-lang/rustup.git synced 2026-08-01 06:53:55 +08:00
Code Issues Packages Projects Releases Wiki Activity
rustup/print.html

1526 lines
107 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>The rustup book</title>
<meta name="robots" content="noindex">
<!-- Custom HTML head -->
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff">
<link rel="icon" href="favicon-de23e50b.svg">
<link rel="shortcut icon" href="favicon-8114d1fc.png">
<link rel="stylesheet" href="css/variables-8adf115d.css">
<link rel="stylesheet" href="css/general-2459343d.css">
<link rel="stylesheet" href="css/chrome-ae938929.css">
<link rel="stylesheet" href="css/print-9e4910d8.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="fonts/fonts-9644e21d.css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" id="mdbook-highlight-css" href="highlight-493f70e1.css">
<link rel="stylesheet" id="mdbook-tomorrow-night-css" href="tomorrow-night-4c0ae647.css">
<link rel="stylesheet" id="mdbook-ayu-highlight-css" href="ayu-highlight-3fdfc3ac.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "";
const default_light_theme = "light";
const default_dark_theme = "navy";
window.path_to_searchindex_js = "searchindex-e5c8de8e.js";
</script>
<!-- Start loading toc.js asap -->
<script src="toc-2fcce5c9.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="mdbook-body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('light')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="mdbook-sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("mdbook-sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
sidebar_toggle.checked = false;
}
if (sidebar === 'visible') {
sidebar_toggle.checked = true;
} else {
html.classList.remove('sidebar-visible');
}
</script>
<nav id="mdbook-sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="toc.html"></iframe>
</noscript>
<div id="mdbook-sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</div>
</nav>
<div id="mdbook-page-wrapper" class="page-wrapper">
<div class="page">
<div id="mdbook-menu-bar-hover-placeholder"></div>
<div id="mdbook-menu-bar" class="menu-bar sticky">
<div class="left-buttons">
<label id="mdbook-sidebar-toggle" class="icon-button" for="mdbook-sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="mdbook-sidebar">
<span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M0 96C0 78.3 14.3 64 32 64H416c17.7 0 32 14.3 32 32s-14.3 32-32 32H32C14.3 128 0 113.7 0 96zM0 256c0-17.7 14.3-32 32-32H416c17.7 0 32 14.3 32 32s-14.3 32-32 32H32c-17.7 0-32-14.3-32-32zM448 416c0 17.7-14.3 32-32 32H32c-17.7 0-32-14.3-32-32s14.3-32 32-32H416c17.7 0 32 14.3 32 32z"/></svg></span>
</label>
<button id="mdbook-theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="mdbook-theme-list">
<span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M371.3 367.1c27.3-3.9 51.9-19.4 67.2-42.9L600.2 74.1c12.6-19.5 9.4-45.3-7.6-61.2S549.7-4.4 531.1 9.6L294.4 187.2c-24 18-38.2 46.1-38.4 76.1L371.3 367.1zm-19.6 25.4l-116-104.4C175.9 290.3 128 339.6 128 400c0 3.9 .2 7.8 .6 11.6c1.8 17.5-10.2 36.4-27.8 36.4H96c-17.7 0-32 14.3-32 32s14.3 32 32 32H240c61.9 0 112-50.1 112-112c0-2.5-.1-5-.2-7.5z"/></svg></span>
</button>
<ul id="mdbook-theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="mdbook-theme-default_theme">Auto</button></li>
<li role="none"><button role="menuitem" class="theme" id="mdbook-theme-light">Light</button></li>
<li role="none"><button role="menuitem" class="theme" id="mdbook-theme-rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="mdbook-theme-coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="mdbook-theme-navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="mdbook-theme-ayu">Ayu</button></li>
</ul>
<button id="mdbook-search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="mdbook-searchbar">
<span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M416 208c0 45.9-14.9 88.3-40 122.7L502.6 457.4c12.5 12.5 12.5 32.8 0 45.3s-32.8 12.5-45.3 0L330.7 376c-34.4 25.2-76.8 40-122.7 40C93.1 416 0 322.9 0 208S93.1 0 208 0S416 93.1 416 208zM208 352c79.5 0 144-64.5 144-144s-64.5-144-144-144S64 128.5 64 208s64.5 144 144 144z"/></svg></span>
</button>
</div>
<h1 class="menu-title">The rustup book</h1>
<div class="right-buttons">
<a href="print.html" title="Print this book" aria-label="Print this book">
<span class=fa-svg id="print-button"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M128 0C92.7 0 64 28.7 64 64v96h64V64H354.7L384 93.3V160h64V93.3c0-17-6.7-33.3-18.7-45.3L400 18.7C388 6.7 371.7 0 354.7 0H128zM384 352v32 64H128V384 368 352H384zm64 32h32c17.7 0 32-14.3 32-32V256c0-35.3-28.7-64-64-64H64c-35.3 0-64 28.7-64 64v96c0 17.7 14.3 32 32 32H64v64c0 35.3 28.7 64 64 64H384c35.3 0 64-28.7 64-64V384zm-16-88c-13.3 0-24-10.7-24-24s10.7-24 24-24s24 10.7 24 24s-10.7 24-24 24z"/></svg></span>
</a>
<a href="https://github.com/rust-lang/rustup/tree/HEAD/doc/user-guide" title="Git repository" aria-label="Git repository">
<span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 496 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"/></svg></span>
</a>
</div>
</div>
<div id="mdbook-search-wrapper" class="hidden">
<form id="mdbook-searchbar-outer" class="searchbar-outer">
<div class="search-wrapper">
<input type="search" id="mdbook-searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="mdbook-searchresults-outer" aria-describedby="searchresults-header">
<div class="spinner-wrapper">
<span class=fa-svg id="fa-spin"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M304 48c0-26.5-21.5-48-48-48s-48 21.5-48 48s21.5 48 48 48s48-21.5 48-48zm0 416c0-26.5-21.5-48-48-48s-48 21.5-48 48s21.5 48 48 48s48-21.5 48-48zM48 304c26.5 0 48-21.5 48-48s-21.5-48-48-48s-48 21.5-48 48s21.5 48 48 48zm464-48c0-26.5-21.5-48-48-48s-48 21.5-48 48s21.5 48 48 48s48-21.5 48-48zM142.9 437c18.7-18.7 18.7-49.1 0-67.9s-49.1-18.7-67.9 0s-18.7 49.1 0 67.9s49.1 18.7 67.9 0zm0-294.2c18.7-18.7 18.7-49.1 0-67.9S93.7 56.2 75 75s-18.7 49.1 0 67.9s49.1 18.7 67.9 0zM369.1 437c18.7 18.7 49.1 18.7 67.9 0s18.7-49.1 0-67.9s-49.1-18.7-67.9 0s-18.7 49.1 0 67.9z"/></svg></span>
</div>
</div>
</form>
<div id="mdbook-searchresults-outer" class="searchresults-outer hidden">
<div id="mdbook-searchresults-header" class="searchresults-header"></div>
<ul id="mdbook-searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script>
document.getElementById('mdbook-sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('mdbook-sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#mdbook-sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="mdbook-content" class="content">
<main>
<h1 id="introduction"><a class="header" href="#introduction">Introduction</a></h1>
<p><em>rustup</em> installs <a href="https://www.rust-lang.org">The Rust Programming Language</a> from the official
release channels, enabling you to easily switch between stable, beta, and
nightly compilers and keep them updated. It makes cross-compiling simpler with
binary builds of the standard library for common platforms. And it runs on all
platforms Rust supports.</p>
<p>Check out the <a href="#concepts">Concepts</a> chapter for an overview of how rustup works and some
of the terminology it uses. The <a href="#installation">Installation</a> chapter covers installing
rustup and getting started.</p>
<p>The source code of rustup and this manual may be found at
<a href="https://github.com/rust-lang/rustup">https://github.com/rust-lang/rustup</a>. If you find a problem, check out the
<a href="https://github.com/rust-lang/rustup/issues">issue tracker</a>.</p>
<p>Release notes for rustup may be found in the <a href="https://github.com/rust-lang/rustup/blob/HEAD/CHANGELOG.md">CHANGELOG</a>.</p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="installation"><a class="header" href="#installation">Installation</a></h1>
<p>Follow the instructions at <a href="https://www.rust-lang.org/tools/install">https://www.rust-lang.org/tools/install</a>. If that
doesn’t work for you there are <a href="#other-installation-methods">other installation methods</a>.</p>
<p><code>rustup</code> installs <code>rustc</code>, <code>cargo</code>, <code>rustup</code> and other standard tools to
Cargo’s <code>bin</code> directory. On Unix it is located at <code>$HOME/.cargo/bin</code> and on
Windows at <code>%USERPROFILE%\.cargo\bin</code>. This is the same directory that <code>cargo install</code> will install Rust programs and Cargo plugins.</p>
<p>This directory will be in your <code>$PATH</code> environment variable, which means you
can run them from the shell without further configuration. Open a <em>new</em> shell
and type the following:</p>
<pre><code class="language-console">rustc --version
</code></pre>
<p>If you see something like <code>rustc 1.19.0 (0ade33941 2017-07-17)</code> then you are
ready to Rust. If you decide Rust isn’t your thing, you can completely remove
it from your system by running <code>rustup self uninstall</code>.</p>
<h2 id="choosing-where-to-install"><a class="header" href="#choosing-where-to-install">Choosing where to install</a></h2>
<p><code>rustup</code> allows you to customise your installation by setting the environment
variables <code>CARGO_HOME</code> and <code>RUSTUP_HOME</code> before running the <code>rustup-init</code>
executable. As mentioned in the <a href="#environment-variables">Environment Variables</a> section, <code>RUSTUP_HOME</code>
sets the root <code>rustup</code> folder, which is used for storing installed toolchains
and configuration options. <code>CARGO_HOME</code> contains cache files used by <a href="https://doc.rust-lang.org/cargo/">cargo</a>.</p>
<p>Note that you will need to ensure these environment variables are always set
and that <code>CARGO_HOME/bin</code> is in the <code>$PATH</code> environment variable when using
the toolchain.</p>
<h2 id="installing-nightly"><a class="header" href="#installing-nightly">Installing nightly</a></h2>
<p>If you specify the <a href="#channels">nightly channel</a> when installing <code>rustup</code>, the
<code>rustup-init</code> script will do a “forced” installation by default. A “forced”
installation means it will install the nightly channel regardless of whether
it might be missing <a href="#components">components</a> that you want. If you want to install rustup
with the nightly channel, and ensure it has the components that you want, you
will need to do this in two phases. For example, if you want to make a fresh
installation of <code>rustup</code> and then install <code>nightly</code> along with <code>clippy</code> or
<code>miri</code>, first install <code>rustup</code> without a toolchain:</p>
<pre><code class="language-console">curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- --default-toolchain none -y
</code></pre>
<p>Next you can install <code>nightly</code> allowing <code>rustup</code> to downgrade until it finds
the components you need:</p>
<pre><code class="language-console">rustup toolchain install nightly --allow-downgrade --profile minimal --component clippy
</code></pre>
<p>This can be used to great effect in CI, to get you a toolchain rapidly which
meets your criteria.</p>
<h2 id="enable-tab-completion-for-bash-fish-zsh-or-powershell"><a class="header" href="#enable-tab-completion-for-bash-fish-zsh-or-powershell">Enable tab completion for Bash, Fish, Zsh, or PowerShell</a></h2>
<p><code>rustup</code> now supports generating completion scripts for Bash, Fish, Zsh, and
PowerShell. See <code>rustup help completions</code> for full details, but the gist is as
simple as using one of the following:</p>
<pre><code class="language-console"># Bash
$ rustup completions bash &gt; ~/.local/share/bash-completion/completions/rustup
# Bash (macOS/Homebrew)
$ rustup completions bash &gt; $(brew --prefix)/etc/bash_completion.d/rustup.bash-completion
# Fish
$ mkdir -p ~/.config/fish/completions
$ rustup completions fish &gt; ~/.config/fish/completions/rustup.fish
# Zsh
$ rustup completions zsh &gt; ~/.zfunc/_rustup
# PowerShell v5.0+
$ rustup completions powershell &gt;&gt; $PROFILE.CurrentUserCurrentHost
# or
$ rustup completions powershell | Out-String | Invoke-Expression
</code></pre>
<p><strong>Note</strong>: you may need to restart your shell in order for the changes to take
effect.</p>
<p>For <code>zsh</code>, you must then add the following line in your <code>~/.zshrc</code> before
<code>compinit</code>:</p>
<pre><code class="language-zsh">fpath+=~/.zfunc
</code></pre>
<p>In Xonsh you can reuse Fish completion by installing <a href="https://github.com/xonsh/xontrib-fish-completer">xontrib-fish-completer</a>.</p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="windows"><a class="header" href="#windows">Windows</a></h1>
<p><code>rustup</code> works the same on Windows as it does on Unix, but there are some
special considerations for Rust developers on Windows. As <a href="https://www.rust-lang.org/tools/install?platform_override=win">mentioned on the
Rust download page</a>, there are two <a href="https://en.wikipedia.org/wiki/Application_binary_interface">ABIs</a> in use on Windows:
the native (MSVC) ABI used by <a href="https://visualstudio.microsoft.com/">Visual Studio</a>, and the GNU ABI used by the
<a href="https://gcc.gnu.org/">GCC toolchain</a>. Which version of Rust you need depends largely on what C/C++
libraries you want to interoperate with: for interop with software produced by
Visual Studio use the MSVC build of Rust; for interop with GNU software built
using the <a href="https://www.msys2.org/">MinGW/MSYS2 toolchain</a> use the GNU build.</p>
<p>When targeting the MSVC ABI, Rust additionally requires an <a href="#msvc-prerequisites">installation of
Visual Studio</a> so <code>rustc</code> can use its linker and libraries.</p>
<p>When targeting the GNU ABI, no additional software is strictly required for basic use.
However, many library crates will not be able to compile until the full <a href="https://www.msys2.org/">MSYS2</a> with MinGW has been installed.</p>
<p>By default <code>rustup</code> on Windows configures Rust to target the MSVC ABI, that is
a target tuple of either <code>i686-pc-windows-msvc</code>, <code>x86_64-pc-windows-msvc</code>, or <code>aarch64-pc-windows-msvc</code>
depending on the CPU architecture of the host Windows OS. The toolchains that
<code>rustup</code> chooses to install, unless told otherwise through the <a href="#toolchain-specification">toolchain
specification</a>, will be compiled to run on that target tuple host and will
target that tuple by default.</p>
<p>You can change this behavior with <code>rustup set default-host</code> or during
installation.</p>
<p>For example, to explicitly select the 32-bit MSVC host:</p>
<pre><code class="language-console">$ rustup set default-host i686-pc-windows-msvc
</code></pre>
<p>Or to choose the 64 bit GNU toolchain:</p>
<pre><code class="language-console">$ rustup set default-host x86_64-pc-windows-gnu
</code></pre>
<p>Since the MSVC ABI provides the best interoperation with other Windows
software it is recommended for most purposes. The GNU toolchain is always
available, even if you don’t use it by default. Just install it with <code>rustup toolchain install</code>:</p>
<pre><code class="language-console">$ rustup toolchain install stable-gnu
</code></pre>
<p>You don’t need to switch toolchains to support all windows targets though; a
single toolchain supports all four x86 windows targets:</p>
<pre><code class="language-console">$ rustup target add x86_64-pc-windows-msvc
$ rustup target add x86_64-pc-windows-gnu
$ rustup target add i686-pc-windows-msvc
$ rustup target add i686-pc-windows-gnu
</code></pre>
<p>See the <a href="#cross-compilation">Cross-compilation</a> chapter for more details on specifying different
targets with the same compiler.</p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="msvc-prerequisites"><a class="header" href="#msvc-prerequisites">MSVC prerequisites</a></h1>
<p>To compile programs into an exe file, Rust requires a linker, libraries and Windows API import libraries.
For <code>msvc</code> targets these can be acquired through Visual Studio.</p>
<h2 id="automatic-install"><a class="header" href="#automatic-install">Automatic install</a></h2>
<p>If you don’t have Visual Studio already installed then <a href="https://rustup.rs">rustup-init</a> will offer to automatically install the prerequisites.
Doing so means you can skip the rest of this page.
However, it installs Visual Studio Community edition which may not be appropriate for all users.
It is free for individuals, academic and open source use, but not for other uses, such as in proprietary enterprise software.
Users should ask their organisation which edition is right for them.
See <a href="https://visualstudio.microsoft.com/license-terms/">licensing terms</a> for more details.</p>
<h2 id="winget"><a class="header" href="#winget">WinGet</a></h2>
<p>Alternatively Visual Studio can be installed via the <a href="https://learn.microsoft.com/en-us/windows/package-manager/winget/">WinGet</a> package manager, which should be available by default on recent versions of Windows.
Run the following command in powershell or the command prompt:</p>
<pre><code>winget install --id Microsoft.VisualStudio.2022.Community --source winget --force --override "--add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 --add Microsoft.VisualStudio.Component.VC.Tools.ARM64 --add Microsoft.VisualStudio.Component.Windows11SDK.22621 --addProductLang En-us"
</code></pre>
<p>You can replace “Community” with “BuildTools” in the above command if you already have a Visual Studio license.</p>
<h3 id="missing-windows-sdk"><a class="header" href="#missing-windows-sdk">Missing Windows SDK</a></h3>
<p>If after running the above command the Windows 11 SDK is missing then you may need to manually install it, which can also be done via WinGet.
First search for the available versions:</p>
<pre><code>winget search --source winget --id Microsoft.WindowsSDK.
</code></pre>
<p>This should display a table of results. that will look like this:</p>
<pre><code>Name Id Version
----------------------------------------------------------------------------------------------------------
Windows Software Development Kit Microsoft.WindowsSDK.10.0.22000 10.0.22000.832
Windows Software Development Kit - Windows 10.0.22621.2428 Microsoft.WindowsSDK.10.0.22621 10.0.22621.2428
Windows Software Development Kit - Windows 10.0.26100.4188 Microsoft.WindowsSDK.10.0.26100 10.0.26100.4188
</code></pre>
<p>Pick the Id with the latest version and install that via <code>winget install</code>.
For example, to install <code>Microsoft.WindowsSDK.10.0.26100</code> run:</p>
<pre><code>winget install --source winget --id Microsoft.WindowsSDK.10.0.26100
</code></pre>
<h2 id="manual-install"><a class="header" href="#manual-install">Manual install</a></h2>
<p><a href="https://visualstudio.microsoft.com/downloads/">Download Visual Studio</a>.
Rust supports Visual Studio 2017 and later but it is recommended that you use the latest version (currently 2022) for new projects.
You can opt to download only the Build Tools for Visual Studio, which does not include the IDE.
However this requires you already have a license to the Community, Professional or Enterprise edition.</p>
<p>Once you’ve downloaded and started the installer, the easiest way to get everything installed is to select “Desktop Development with C++”.
This will include the necessary components.
On the “Language Packs” tab, make sure the English language pack is installed in addition to your preferred language.</p>
<p>If you want more details on the installation process or want to further customize the install then follow the walkthrough below.
Otherwise complete the Visual Studio install and continue with installing Rust.</p>
<h2 id="walkthrough-installing-visual-studio-2022"><a class="header" href="#walkthrough-installing-visual-studio-2022">Walkthrough: Installing Visual Studio 2022</a></h2>
<p>This walkthrough uses the Community edition of Visual Studio but the Professional, Enterprise and the Build Tools all work the same way.</p>
<p>The installer will start by linking to the <a href="https://visualstudio.microsoft.com/license-terms/">license</a> and for your edition of Visual Studio and then preparing the installer.</p>
<p><img src="installation/images/step1.png" alt="Accept the license">
<img src="installation/images/step2.png" alt="Installing the installer"></p>
<p>Once this finishes, you can then select the components to be installed.
Here we use the “Workload” tab to select the “Desktop Development with C++” workload.
This will includes all needed components for Rust:
<img src="installation/images/step3.png" alt="Select the C++ Workload"></p>
<h3 id="installing-only-the-required-components-optional"><a class="header" href="#installing-only-the-required-components-optional">Installing only the required components (optional)</a></h3>
<p>If you’d like a more minimal install (and won’t be doing C++ development) then you can use the “Individual Components” tab to select just the essentials, which are:</p>
<ul>
<li>MSVC v143 - VS 2022 C++ x64/x86 build tools (Latest)</li>
<li>Windows 11 SDK (10.0.22621.0)</li>
</ul>
<p>Note that the specific version of the Windows SDK doesn’t matter for pure Rust code but if using C++ as well you’ll likely want either the latest or whichever version is required by the C++ project (or both).</p>
<p><img src="installation/images/component-msvc.png" alt="Select the latest MSVC component">
<img src="installation/images/component-sdk.png" alt="Select the Windows 11 SDK component"></p>
<h3 id="adding-language-packs-optional"><a class="header" href="#adding-language-packs-optional">Adding Language Packs (optional)</a></h3>
<p>After choosing the components, you may also want to select the language packs to install.
Switch to the “Language Packs” tab and add the languages.
It is recommended that you add the English language pack in addition to your preferred language.
This will provide English language error messages, which may help when reporting errors.</p>
<p><img src="installation/images/step4.png" alt="Add the English language"></p>
<h3 id="completing-the-install"><a class="header" href="#completing-the-install">Completing the install</a></h3>
<p>Finally click the install button and wait for everything to be installed.</p>
<p><img src="installation/images/step5.png" alt="Wait for the install to complete"></p>
<p>Once finished, you can continue on to installing Rust.</p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="other-installation-methods"><a class="header" href="#other-installation-methods">Other installation methods</a></h1>
<p>The primary installation method, as described at <a href="https://rustup.rs">https://rustup.rs</a>, differs
by platform:</p>
<ul>
<li>On Windows, download and run the <code>rustup-init.exe</code> built for the
<a href="https://static.rust-lang.org/rustup/dist/x86_64-pc-windows-msvc/rustup-init.exe"><code>x86_64-pc-windows-msvc</code></a> or <a href="https://static.rust-lang.org/rustup/dist/aarch64-pc-windows-msvc/rustup-init.exe"><code>aarch64-pc-windows-msvc</code></a> target,
depending on your OS architecture. In general, this is the build of
<code>rustup</code> one should install on Windows. This will require <a href="#msvc-prerequisites">MSVC prerequisites</a>.
If you would prefer to install GNU toolchains or the i686
toolchains by default this can be modified at install time, either
interactively, with the <code>--default-host</code> flag, or after installation
via <code>rustup set default-host</code>.</li>
<li>On Unix, run <code>curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh</code> in your shell. This
downloads and runs <a href="https://static.rust-lang.org/rustup/rustup-init.sh"><code>rustup-init.sh</code></a>, which in turn downloads and runs the
correct version of the <code>rustup-init</code> executable for your platform.</li>
</ul>
<p><code>rustup-init</code> accepts arguments, which can be passed through the shell script.
Some examples:</p>
<pre><code class="language-console">$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- --help
$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- --no-modify-path
$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- --default-toolchain nightly
$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- --default-toolchain none
$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- --profile minimal --default-toolchain nightly
</code></pre>
<h2 id="using-a-package-manager"><a class="header" href="#using-a-package-manager">Using a package manager</a></h2>
<blockquote>
<p>Please note that the rustup project is not maintaining any package mentioned in this section.
If you have encountered any problems installing <code>rustup</code> with a package manager,
please contact the package maintainer(s) for further information.</p>
</blockquote>
<h3 id="general-tips"><a class="header" href="#general-tips">General tips</a></h3>
<p>Different package managers take slightly different approaches towards managing rustup.
After installing rustup with your favorite package manager, there are usually two possibilities:</p>
<ul>
<li>
<p>If your package manager has made the <code>rustup</code> command available
together with proxies for Rust tools such as <code>rustc</code> and <code>cargo</code>,
picking a default toolchain (e.g. <code>stable</code>) would usually be enough:</p>
<pre><code class="language-sh">$ rustup default stable
</code></pre>
<blockquote>
<p>As of 2024/12/23, this is the case for
<a href="https://packages.debian.org/search?searchon=names&amp;keywords=rustup">APT</a>,
<a href="https://formulae.brew.sh/formula/rustup">homebrew</a>
and <a href="https://wiki.archlinux.org/title/Rust#Arch_Linux_package">pacman</a>.</p>
</blockquote>
</li>
<li>
<p>If your package manager has only made the <code>rustup-init</code> command available, simply run:</p>
<pre><code class="language-sh">$ rustup-init
</code></pre>
<p>This will allow you to perform the initial setup of <code>rustup</code>, populate all the proxies
managed by rustup, and install a default toolchain.</p>
<blockquote>
<p>As of 2024/12/23, this is the case for
<a href="https://developer.fedoraproject.org/tech/languages/rust/further-reading.html">DNF</a>.</p>
</blockquote>
</li>
</ul>
<p>When the installation is completed, please make sure that the rustup proxies
(usually under <code>$HOME/.cargo/bin</code>) are <a href="#ensure-the-correct-path-configuration">correctly exposed</a> via your <code>$PATH</code>,
and you should be able to run <code>rustup</code>, <code>rustc</code>, <code>cargo</code>, etc. normally.</p>
<h3 id="apt"><a class="header" href="#apt">APT</a></h3>
<p>Starting from Debian 13 (trixie) and Ubuntu 24.04 (noble),
you may use <code>apt</code> to install <code>rustup</code>:</p>
<pre><code class="language-sh">$ sudo apt install rustup
</code></pre>
<h3 id="homebrew"><a class="header" href="#homebrew">Homebrew</a></h3>
<p>You can use <code>brew</code> to install <code>rustup</code><sup class="footnote-reference" id="fr-not-rust-1"><a href="#footnote-not-rust">1</a></sup>:</p>
<pre><code class="language-sh">$ brew install rustup
</code></pre>
<p>Please note that Rust tools like <code>rustc</code> and <code>cargo</code> are not available via <code>$PATH</code> by default
in this <code>rustup</code> distribution
(see <a href="https://github.com/Homebrew/homebrew-core/pull/177582">homebrew-core#177582</a> for more details).
You might want to add <code>$(brew --prefix rustup)/bin</code> to <code>$PATH</code> to make them easier to access.</p>
<h2 id="manual-installation"><a class="header" href="#manual-installation">Manual installation</a></h2>
<p>You can manually download <code>rustup-init</code> for a given target from
<code>https://static.rust-lang.org/rustup/dist/{target-tuple}/rustup-init[.exe]</code><sup class="footnote-reference" id="fr-msys2-1"><a href="#footnote-msys2">2</a></sup> <sup class="footnote-reference" id="fr-msvc-1"><a href="#footnote-msvc">3</a></sup>.</p>
<details>
<summary>Direct links</summary>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/aarch64-apple-darwin/rustup-init">aarch64-apple-darwin</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/aarch64-apple-darwin/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/aarch64-linux-android/rustup-init">aarch64-linux-android</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/aarch64-linux-android/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/aarch64-pc-windows-gnullvm/rustup-init.exe">aarch64-pc-windows-gnullvm</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/aarch64-pc-windows-gnullvm/rustup-init.exe.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/aarch64-pc-windows-msvc/rustup-init.exe">aarch64-pc-windows-msvc</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/aarch64-pc-windows-msvc/rustup-init.exe.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/aarch64-unknown-linux-gnu/rustup-init">aarch64-unknown-linux-gnu</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/aarch64-unknown-linux-gnu/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/aarch64-unknown-linux-musl/rustup-init">aarch64-unknown-linux-musl</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/aarch64-unknown-linux-musl/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/aarch64-unknown-freebsd/rustup-init">aarch64-unknown-freebsd</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/aarch64-unknown-freebsd/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/arm-linux-androideabi/rustup-init">arm-linux-androideabi</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/arm-linux-androideabi/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/arm-unknown-linux-gnueabi/rustup-init">arm-unknown-linux-gnueabi</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/arm-unknown-linux-gnueabi/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/arm-unknown-linux-gnueabihf/rustup-init">arm-unknown-linux-gnueabihf</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/arm-unknown-linux-gnueabihf/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/armv7-linux-androideabi/rustup-init">armv7-linux-androideabi</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/armv7-linux-androideabi/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/armv7-unknown-linux-gnueabihf/rustup-init">armv7-unknown-linux-gnueabihf</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/armv7-unknown-linux-gnueabihf/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/i686-apple-darwin/rustup-init">i686-apple-darwin</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/i686-apple-darwin/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/i686-linux-android/rustup-init">i686-linux-android</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/i686-linux-android/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/i686-pc-windows-gnu/rustup-init.exe">i686-pc-windows-gnu</a><sup class="footnote-reference" id="fr-msys2-2"><a href="#footnote-msys2">2</a></sup>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/i686-pc-windows-gnu/rustup-init.exe.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/i686-pc-windows-msvc/rustup-init.exe">i686-pc-windows-msvc</a><sup class="footnote-reference" id="fr-msvc-2"><a href="#footnote-msvc">3</a></sup>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/i686-pc-windows-msvc/rustup-init.exe.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/i686-unknown-linux-gnu/rustup-init">i686-unknown-linux-gnu</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/i686-unknown-linux-gnu/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/loongarch64-unknown-linux-gnu/rustup-init">loongarch64-unknown-linux-gnu</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/loongarch64-unknown-linux-gnu/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/loongarch64-unknown-linux-musl/rustup-init">loongarch64-unknown-linux-musl</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/loongarch64-unknown-linux-musl/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/mips-unknown-linux-gnu/rustup-init">mips-unknown-linux-gnu</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/mips-unknown-linux-gnu/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/mips64-unknown-linux-gnuabi64/rustup-init">mips64-unknown-linux-gnuabi64</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/mips64-unknown-linux-gnuabi64/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/mips64el-unknown-linux-gnuabi64/rustup-init">mips64el-unknown-linux-gnuabi64</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/mips64el-unknown-linux-gnuabi64/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/mipsel-unknown-linux-gnu/rustup-init">mipsel-unknown-linux-gnu</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/mipsel-unknown-linux-gnu/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/powerpc-unknown-linux-gnu/rustup-init">powerpc-unknown-linux-gnu</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/powerpc-unknown-linux-gnu/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/powerpc64-unknown-linux-gnu/rustup-init">powerpc64-unknown-linux-gnu</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/powerpc64-unknown-linux-gnu/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/powerpc64-unknown-linux-musl/rustup-init">powerpc64-unknown-linux-musl</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/powerpc64-unknown-linux-musl/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/powerpc64le-unknown-linux-gnu/rustup-init">powerpc64le-unknown-linux-gnu</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/powerpc64le-unknown-linux-gnu/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/powerpc64le-unknown-linux-musl/rustup-init">powerpc64le-unknown-linux-musl</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/powerpc64le-unknown-linux-musl/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/s390x-unknown-linux-gnu/rustup-init">s390x-unknown-linux-gnu</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/s390x-unknown-linux-gnu/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/sparcv9-sun-solaris/rustup-init">sparcv9-sun-solaris</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/sparcv9-sun-solaris/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/x86_64-apple-darwin/rustup-init">x86_64-apple-darwin</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/x86_64-apple-darwin/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/x86_64-linux-android/rustup-init">x86_64-linux-android</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/x86_64-linux-android/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/x86_64-pc-solaris/rustup-init">x86_64-pc-solaris</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/x86_64-pc-solaris/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/x86_64-pc-windows-gnu/rustup-init.exe">x86_64-pc-windows-gnu</a><sup class="footnote-reference" id="fr-msys2-3"><a href="#footnote-msys2">2</a></sup>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/x86_64-pc-windows-gnu/rustup-init.exe.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/x86_64-pc-windows-msvc/rustup-init.exe">x86_64-pc-windows-msvc</a><sup class="footnote-reference" id="fr-msvc-3"><a href="#footnote-msvc">3</a></sup>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/x86_64-pc-windows-msvc/rustup-init.exe.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/x86_64-unknown-freebsd/rustup-init">x86_64-unknown-freebsd</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/x86_64-unknown-freebsd/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/x86_64-unknown-illumos/rustup-init">x86_64-unknown-illumos</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/x86_64-unknown-illumos/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/x86_64-unknown-linux-gnu/rustup-init">x86_64-unknown-linux-gnu</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/x86_64-unknown-linux-gnu/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/x86_64-unknown-linux-musl/rustup-init">x86_64-unknown-linux-musl</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/x86_64-unknown-linux-musl/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
<li><a href="https://static.rust-lang.org/rustup/dist/x86_64-unknown-netbsd/rustup-init">x86_64-unknown-netbsd</a>
<ul>
<li><a href="https://static.rust-lang.org/rustup/dist/x86_64-unknown-netbsd/rustup-init.sha256">sha256 file</a></li>
</ul>
</li>
</ul>
</details>
<p>To get a previous version, use
<code>https://static.rust-lang.org/rustup/archive/{rustup-version}/{target-tuple}/rustup-init[.exe]</code>.</p>
<p>SHA-256 checksums are also available by appending <code>.sha256</code> to the link.</p>
<h2 id="self-compiled-installation"><a class="header" href="#self-compiled-installation">Self-compiled installation</a></h2>
<p>To install <code>rustup</code> from source, check out the git repository from
<a href="https://github.com/rust-lang/rustup">https://github.com/rust-lang/rustup</a> and run <code>cargo run --release</code>. Note that
after installation the <code>rustup</code> toolchains will supersede any pre-existing
toolchains by prepending <code>~/.cargo/bin</code> to the <code>PATH</code> environment variable.</p>
<hr>
<ol class="footnote-definition">
<li id="footnote-not-rust">
<p>This is not to be confused with the <code>rust</code> package,
which is a <code>brew</code>-managed <code>rust</code> toolchain installation. <a href="#fr-not-rust-1">↩</a></p>
</li>
<li id="footnote-msys2">
<p>Windows GNU builds require no additional software for basic use.
However, many library crates will not be able to compile until
the full <a href="https://www.msys2.org/">MSYS2</a> with MinGW has been installed. <a href="#fr-msys2-1">↩</a> <a href="#fr-msys2-2">↩2</a> <a href="#fr-msys2-3">↩3</a></p>
</li>
<li id="footnote-msvc">
<p>MSVC builds of <code>rustup</code> additionally require an <a href="https://visualstudio.microsoft.com/downloads/">installation of
Visual Studio 2019 or the Visual C++ Build Tools 2019</a>. For Visual
Studio, make sure to check the “C++ tools” and “Windows 10 SDK” option. <a href="#fr-msvc-1">↩</a> <a href="#fr-msvc-2">↩2</a> <a href="#fr-msvc-3">↩3</a></p>
</li>
</ol>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="already-installed-rust"><a class="header" href="#already-installed-rust">Already installed Rust?</a></h1>
<p>Other package managers also ship Rust, and you may wish to use the packaged
toolchain, such as for distribution package development. You may also wish to
use a <code>rustup</code>-managed toolchain such as nightly or beta. Normally, <code>rustup</code>
will complain that you already have Rust installed in <code>/usr</code> and refuse to
install. However, you can install Rust via <code>rustup</code> and have it coexist with
your packaged Rust toolchain.</p>
<h2 id="set-up-rustup-with-an-existing-rust-toolchain"><a class="header" href="#set-up-rustup-with-an-existing-rust-toolchain">Set up rustup with an existing Rust toolchain</a></h2>
<p>When you initially install Rust with <code>rustup</code>, pass the <code>-y</code> option to make it
ignore the packaged Rust toolchain and install a <code>rustup</code>-managed toolchain
into <code>~/.cargo/bin</code>. Add that directory to your <code>$PATH</code> (or let <code>rustup</code> do it
for you by not passing <code>--no-modify-path</code>). Then, to tell <code>rustup</code> about your
system toolchain, run:</p>
<pre><code class="language-console">rustup toolchain link system /usr
</code></pre>
<p>You can then use “system” as a <code>rustup</code> toolchain, just like “nightly”.
For example, using the <a href="#toolchain-override-shorthand">toolchain override shorthand</a>, you can run <code>cargo +system build</code>
to build with the system toolchain, or <code>cargo +nightly build</code> to build with nightly.</p>
<p>If you wish to develop with the system toolchain (e.g. for distribution packages),
you may want to make it your <a href="#default-toolchain">default toolchain</a>:</p>
<pre><code class="language-console">rustup default system
</code></pre>
<h2 id="ensure-the-correct-path-configuration"><a class="header" href="#ensure-the-correct-path-configuration">Ensure the correct <code>$PATH</code> configuration</a></h2>
<p>There are times when the above steps don’t work, and you may see strange error
messages when running commands that should have been proxied by rustup.
For example, when running <code>cargo +stable --version</code>, you may encounter the
following error:</p>
<pre><code class="language-text">error: no such command: `+stable`
Cargo does not handle `+toolchain` directives.
Did you mean to invoke `cargo` through `rustup` instead?
</code></pre>
<p>This means <code>cargo</code> is currently not a <code>rustup</code> proxy, and your <code>$PATH</code> needs
to be fixed.</p>
<p>In fact, on any machine with rustup installed, you would like to have <strong>rustup
proxies showing up first in <code>$PATH</code></strong>, shadowing any other Rust installations.
Don’t worry: these shadowed installations can then be adopted by rustup with the
<code>rustup toolchain link</code> command as mentioned above.</p>
<p>The exact steps to be taken to make rustup proxies come first may vary according
to your system environment, but usually it is about changing the evaluation
order of certain lines in your shell configuration file(s).</p>
<p>To make it clearer, let’s look at the example of a Mac with both regular rustup
fetched from <a href="https://rustup.rs">rustup.rs</a> and homebrew-installed <code>rust</code>.
The <strong>right way</strong> to configure <code>.profile</code> in this environment would be:</p>
<pre><code class="language-bash">eval $(/opt/homebrew/bin/brew shellenv)
. $HOME/.cargo/env
</code></pre>
<p>In this example, both of these lines <em>prepend</em> to <code>$PATH</code>, so the last one
takes over, letting the rustup proxies shadow the homebrew-installed <code>rust</code>.
On the other hand, putting these lines the other way around will cause the
aforementioned error.</p>
<p>When in doubt, you can always debug your shell configuration by printing the
status of your current <code>$PATH</code> with <code>echo $PATH | xargs -n1</code> and paying
attention to the order of <code>$CARGO_HOME/bin</code> (which defaults to
<code>$HOME/.cargo/bin</code>) compared to your package manager’s <code>bin</code> directory.</p>
<p>After the fix, the output of <code>cargo +stable --version</code> should be similar to one
of the following, depending on whether you have had the <code>stable</code> toolchain
installed:</p>
<ul>
<li>
<pre><code class="language-text">cargo 1.85.1 (d73d2caf9 2024-12-31)
</code></pre>
</li>
<li>
<pre><code class="language-text">error: toolchain 'stable' is not installed
</code></pre>
</li>
</ul>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="concepts"><a class="header" href="#concepts">Concepts</a></h1>
<h2 id="how-rustup-works"><a class="header" href="#how-rustup-works">How rustup works</a></h2>
<p><code>rustup</code> is a <em>toolchain multiplexer</em>. It installs and manages many Rust
toolchains and presents them all through a single set of tools installed to
<code>~/.cargo/bin</code>. The <a href="https://doc.rust-lang.org/rustc/"><code>rustc</code></a> and <a href="https://doc.rust-lang.org/cargo/"><code>cargo</code></a> executables installed in
<code>~/.cargo/bin</code> are <em><a href="#proxies">proxies</a></em> that delegate to the real toolchain. <code>rustup</code>
then provides mechanisms to easily change the active toolchain by
reconfiguring the behavior of the proxies.</p>
<p>So when <code>rustup</code> is first installed, running <code>rustc</code> will run the proxy in
<code>$HOME/.cargo/bin/rustc</code>, which in turn will run the stable compiler. If you
later <em>change the default toolchain</em> to nightly with <code>rustup default nightly</code>,
then that same proxy will run the <code>nightly</code> compiler instead.</p>
<p>This is similar to Ruby’s <a href="https://github.com/rbenv/rbenv">rbenv</a>, Python’s <a href="https://github.com/yyuu/pyenv">pyenv</a>, or Node’s <a href="https://github.com/creationix/nvm">nvm</a>.</p>
<h2 id="terminology"><a class="header" href="#terminology">Terminology</a></h2>
<ul>
<li>
<p><strong>channel</strong> — Rust is released to three different “channels”: stable, beta,
and nightly. See the <a href="#channels">Channels</a> chapter for more details.</p>
</li>
<li>
<p><strong>toolchain</strong> — A “toolchain” is a complete installation of the Rust
compiler (<code>rustc</code>) and related tools (like <code>cargo</code>). A <a href="#toolchains">toolchain
specification</a> includes the release channel or version, and the host
platform that the toolchain runs on.</p>
</li>
<li>
<p><strong>target</strong> — <code>rustc</code> is capable of generating code for many platforms. The
“target” specifies the platform that the code will be generated for. By
default, <code>cargo</code> and <code>rustc</code> use the host toolchain’s platform as the
target. To build for a different target, usually the target’s standard
library needs to be installed first via the <code>rustup target</code> command. See the
<a href="#cross-compilation">Cross-compilation</a> chapter for more details.</p>
</li>
<li>
<p><strong>component</strong> — Each release of Rust includes several “components”, some of
which are required (like <code>rustc</code>) and some that are optional (like
<a href="https://github.com/rust-lang/rust-clippy"><code>clippy</code></a>). See the <a href="#components">Components</a> chapter for more detail.</p>
</li>
<li>
<p><strong>profile</strong> — In order to make it easier to work with components, a
“profile” defines a grouping of components. See the <a href="#profiles">Profiles</a> chapter for
more details.</p>
</li>
<li>
<p><strong>proxy</strong> — A wrapper for a common Rust component (like <code>rustc</code>), built to forward
CLI invocations to the active Rust toolchain. See the <a href="#proxies">Proxies</a> chapter for more details.</p>
</li>
</ul>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="channels"><a class="header" href="#channels">Channels</a></h1>
<p>Rust is released to three different “channels”: stable, beta, and nightly. The
stable releases are made every 6 weeks (with occasional point releases). Beta
releases are the version that will appear in the next stable release. Nightly
releases are made every night. See <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">The Rust Book</a> for more details
on Rust’s train release model. The release schedule is posted to the <a href="https://forge.rust-lang.org/">Rust
Forge</a>. <code>rustup</code> assists with installing different channels, keeping them
up-to-date, and easily switching between them.</p>
<p>After a release channel has been installed, <code>rustup</code> can be used to update the
installed version to the latest release on that channel. See the <a href="#keeping-rust-up-to-date">Keeping rust
up to date</a> section for more information.</p>
<p><code>rustup</code> can also install specific versions of Rust, such as <code>1.45.2</code> or
<code>nightly-2020-07-27</code>. See the <a href="#toolchains">Toolchains</a> chapter for more information on
installing different channels and releases. See the <a href="#overrides">Overrides</a> chapter for
details on switching between toolchains and pinning your project to a specific
toolchain.</p>
<h2 id="working-with-nightly-rust"><a class="header" href="#working-with-nightly-rust">Working with nightly Rust</a></h2>
<p><code>rustup</code> gives you easy access to the nightly compiler and its <a href="https://doc.rust-lang.org/unstable-book/">experimental
features</a>. To add it just run <code>rustup toolchain install nightly</code>:</p>
<pre><code class="language-console">$ rustup toolchain install nightly
info: syncing channel updates for 'nightly'
info: downloading toolchain manifest
info: downloading component 'rustc'
info: downloading component 'rust-std'
info: downloading component 'rust-docs'
info: downloading component 'cargo'
info: installing component 'rustc'
info: installing component 'rust-std'
info: installing component 'rust-docs'
info: installing component 'cargo'
nightly installed: rustc 1.9.0-nightly (02310fd31 2016-03-19)
</code></pre>
<p>Now Rust nightly is installed, but not activated. To test it out you can run a
command from the nightly toolchain like</p>
<pre><code class="language-console">$ rustup run nightly rustc --version
rustc 1.9.0-nightly (02310fd31 2016-03-19)
</code></pre>
<p>But more likely you want to use it for a while. To switch to nightly globally,
change <a href="#default-toolchain">the default</a> with <code>rustup default nightly</code>:</p>
<pre><code class="language-console">$ rustup default nightly
info: using existing install for 'nightly'
info: default toolchain set to 'nightly'
nightly unchanged: rustc 1.9.0-nightly (02310fd31 2016-03-19)
</code></pre>
<p>Now any time you run <code>cargo</code> or <code>rustc</code> you will be running the nightly
compiler.</p>
<p>With nightly installed any time you run <code>rustup update</code>, the nightly channel
will be updated in addition to stable:</p>
<pre><code class="language-console">$ rustup update
info: syncing channel updates for 'stable'
info: syncing channel updates for 'nightly'
info: checking for self-update
info: downloading self-update
stable unchanged: rustc 1.7.0 (a5d1e7a59 2016-02-29)
nightly unchanged: rustc 1.9.0-nightly (02310fd31 2016-03-19)
</code></pre>
<h2 id="nightly-availability"><a class="header" href="#nightly-availability">Nightly availability</a></h2>
<p>Nightly toolchains may fail to build, so for any given date and target
platform there may not be a toolchain available. Furthermore, nightly builds
may be published with missing non-default <a href="#components">components</a> (such as <a href="https://github.com/rust-lang/rust-clippy"><code>clippy</code></a>).
As such, it can be difficult to find fully-working nightlies. Use the
<a href="https://rust-lang.github.io/rustup-components-history/">rustup-components-history</a> project to find the build status of recent
nightly toolchains and components.</p>
<p>When you attempt to install or update the <code>nightly</code> channel, <code>rustup</code> will
check if a required or previously installed component is missing. If it is
missing, <code>rustup</code> will automatically search for an older release that contains
the required components. There are several ways to change this behavior:</p>
<ul>
<li>Use the <code>--force</code> flag to <code>rustup toolchain install</code> to force it to install
the most recent version even if there is a missing component.</li>
<li>Use the <code>--profile</code> flag to <code>rustup toolchain install</code> to use a different
profile that does not contain the missing component. For example,
<code>--profile=minimal</code> should always work, as the minimal set is required to
exist. See the <a href="#profiles">Profiles</a> chapter for more detail.</li>
<li>Install a specific date that contains the components you need. For example,
<code>rustup toolchain install nightly-2020-07-27</code>. You can then use <a href="#overrides">overrides</a>
to pin to that specific release.</li>
</ul>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="toolchains"><a class="header" href="#toolchains">Toolchains</a></h1>
<p>Many <code>rustup</code> commands deal with <em>toolchains</em>, a single installation of the
Rust compiler. <code>rustup</code> supports multiple types of toolchains. The most basic
track the official release <a href="#channels">channels</a>: <em>stable</em>, <em>beta</em> and <em>nightly</em>; but
<code>rustup</code> can also install toolchains from the official archives, for alternate
host platforms, and from local builds.</p>
<h2 id="toolchain-specification"><a class="header" href="#toolchain-specification">Toolchain specification</a></h2>
<p>Standard release channel toolchain names have the following form:</p>
<pre><code>&lt;channel&gt;[-&lt;date&gt;][-&lt;host&gt;]
&lt;channel&gt; = stable|beta|nightly|&lt;versioned&gt;[-&lt;prerelease&gt;]
&lt;versioned&gt; = &lt;major.minor&gt;|&lt;major.minor.patch&gt;
&lt;prerelease&gt; = beta[.&lt;number&gt;]
&lt;date&gt; = YYYY-MM-DD
&lt;host&gt; = &lt;target-tuple&gt;
</code></pre>
<p>‘channel’ is a named release channel, a major and minor version number such as
<code>1.42</code>, or a fully specified version number, such as <code>1.42.0</code>. Channel names
can be optionally appended with an archive date, as in <code>nightly-2014-12-18</code>, in
which case the toolchain is downloaded from the archive for that date.</p>
<p>Finally, the host may be specified as a target tuple. This is most useful for
installing a 32-bit compiler on a 64-bit platform, or for installing the
<a href="https://www.rust-lang.org/tools/install?platform_override=win">MSVC-based toolchain</a> on Windows. For example:</p>
<pre><code class="language-console">$ rustup toolchain install stable-x86_64-pc-windows-msvc
</code></pre>
<p>For convenience, elements of the target tuple that are omitted will be
inferred, so the above could be written:</p>
<pre><code class="language-console">$ rustup toolchain install stable-msvc
</code></pre>
<p>Toolchain names that don’t name a channel instead can be used to name <a href="#custom-toolchains">custom
toolchains</a>.</p>
<h2 id="custom-toolchains"><a class="header" href="#custom-toolchains">Custom toolchains</a></h2>
<p>For convenience of developers working on Rust itself, <code>rustup</code> can manage
local builds of the Rust toolchain. To teach <code>rustup</code> about your build, run:</p>
<pre><code class="language-console">$ rustup toolchain link my-toolchain path/to/my/toolchain/sysroot
</code></pre>
<p>For example, on Ubuntu you might clone <code>rust-lang/rust</code> into <code>~/rust</code>, build
it, and then run:</p>
<pre><code class="language-console">$ rustup toolchain link my-toolchain ~/rust/build/x86_64-unknown-linux-gnu/stage2/
$ rustup default my-toolchain
</code></pre>
<p>Now you can name <code>my-toolchain</code> as any other <code>rustup</code> toolchain. Create a
<code>rustup</code> toolchain for each of your <code>rust-lang/rust</code> workspaces and test them
easily with <code>rustup run my-toolchain rustc</code>.</p>
<p>Because the <code>rust-lang/rust</code> tree does not include Cargo, <em>when <code>cargo</code> is
invoked for a custom toolchain and it is not available, <code>rustup</code> will attempt
to use <code>cargo</code> from one of the release channels</em>, preferring ‘nightly’, then
‘beta’ or ‘stable’.</p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="components"><a class="header" href="#components">Components</a></h1>
<p>Each <a href="#toolchains">toolchain</a> has several “components”, some of which are required (like
<code>rustc</code>) and some that are optional (like <a href="https://github.com/rust-lang/rust-clippy"><code>clippy</code></a>). The <code>rustup component</code> command is used to manage the installed components. For example,
run <code>rustup component list</code> to see a list of available and installed
components.</p>
<p>Components can be added when installing a toolchain with the <code>--component</code>
flag. For example:</p>
<pre><code class="language-console">rustup toolchain install nightly --component rust-docs
</code></pre>
<p>Components can be added to an already-installed toolchain with the <code>rustup component</code> command:</p>
<pre><code class="language-console">rustup component add rust-docs
</code></pre>
<p>To make it easier to choose which components are installed, <code>rustup</code> has the
concept of “profiles” which provide named groupings of different components.
See the <a href="#profiles">Profiles</a> chapter for more detail.</p>
<p>Most components have a target-tuple suffix, such as
<code>rustc-x86_64-apple-darwin</code>, to signify the platform the component is for.</p>
<p>The set of available components may vary with different releases and
toolchains. The following is an overview of the different components:</p>
<ul>
<li><code>rustc</code> — The Rust compiler and <a href="https://doc.rust-lang.org/rustdoc/">Rustdoc</a>.</li>
<li><code>cargo</code> — <a href="https://doc.rust-lang.org/cargo/">Cargo</a> is a package manager and build tool.</li>
<li><code>rustfmt</code> — <a href="https://github.com/rust-lang/rustfmt">Rustfmt</a> is a tool for automatically formatting code.</li>
<li><code>rust-std</code> — This is the Rust <a href="https://doc.rust-lang.org/std/">standard library</a>. There is a separate
<code>rust-std</code> component for each target that <code>rustc</code> supports, such as
<code>rust-std-x86_64-pc-windows-msvc</code>. See the <a href="#cross-compilation">Cross-compilation</a> chapter for
more detail.</li>
<li><code>rust-docs</code> — This is a local copy of the <a href="https://doc.rust-lang.org/">Rust documentation</a>. Use the
<code>rustup doc</code> command to open the documentation in a web browser. Run <code>rustup doc --help</code> for more options.</li>
<li><code>rust-analyzer</code> — <a href="https://rust-analyzer.github.io/">rust-analyzer</a> is a language server that provides support
for editors and IDEs.</li>
<li><code>clippy</code> — <a href="https://github.com/rust-lang/rust-clippy">Clippy</a> is a lint tool that provides extra checks for common
mistakes and stylistic choices.</li>
<li><code>miri</code> — <a href="https://github.com/rust-lang/miri/">Miri</a> is an experimental Rust interpreter, which can be used for
checking for undefined-behavior.</li>
<li><code>rust-src</code> — This is a local copy of the source code of the Rust standard
library. This can be used by some tools, such as <a href="https://rust-analyzer.github.io/">rust-analyzer</a>, to provide
auto-completion for functions within the standard library; <a href="https://github.com/rust-lang/miri/">Miri</a> which is a
Rust interpreter; and Cargo’s experimental <a href="https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#build-std">build-std</a> feature, which allows
you to rebuild the standard library locally.</li>
<li><code>rust-mingw</code> — This contains a linker and platform libraries for building on
the <code>x86_64-pc-windows-gnu</code> platform.</li>
<li><code>llvm-tools</code> — This component contains a collection of <a href="https://llvm.org/">LLVM</a> tools.
<strong>This component has not been stabilized and may change in the future and is
provided as-is.</strong> Availability of individual LLVM tools may
change over LLVM versions (including removal of specific LLVM tools), and
<strong>is not subject to compiler or toolchain stability guarantees</strong>.
See <a href="https://github.com/rust-lang/rust/issues/85658">#85658</a>.</li>
<li><code>rustc-dev</code> — This component contains the compiler as a library. Most users
will not need this; it is only needed for development <em>of</em> tools that link
to the compiler, such as making modifications to <a href="https://github.com/rust-lang/rust-clippy">Clippy</a>.</li>
</ul>
<h3 id="previous-components"><a class="header" href="#previous-components">Previous components</a></h3>
<blockquote>
<p>See <a href="https://rust-lang.github.io/rustup/devel/concepts/components.html#previous-components">here</a>
for the latest version of this section.</p>
</blockquote>
<p>These components have been deprecated and are not published in new Rust releases.</p>
<ul>
<li><code>rls</code> — <a href="https://github.com/rust-lang/rls">RLS</a> is a language server that is deprecated and has been replaced
by rust-analyzer.</li>
<li><code>rust-analysis</code> — Metadata about the standard library, used by <a href="https://github.com/rust-lang/rls">RLS</a>.</li>
<li>The <code>wasm32-wasi</code> target — It has been
<a href="https://blog.rust-lang.org/2024/04/09/updates-to-rusts-wasi-targets.html">renamed</a>
to <code>wasm32-wasip1</code>.</li>
</ul>
<h2 id="component-availability"><a class="header" href="#component-availability">Component availability</a></h2>
<p>Not all components are available for all toolchains. Especially on the nightly
channel, some components may not be included if they are in a broken state.
The current status of all the components may be found on the <a href="https://rust-lang.github.io/rustup-components-history/">rustup
components history</a> page. See the <a href="#nightly-availability">Nightly availability</a> section for more
details.</p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="profiles"><a class="header" href="#profiles">Profiles</a></h1>
<p><code>rustup</code> has the concept of “profiles”. They are groups of <a href="#components">components</a> you
can choose to download while installing a new Rust toolchain. The profiles
available at this time are <code>minimal</code>, <code>default</code>, and <code>complete</code>:</p>
<ul>
<li>The <strong>minimal</strong> profile includes as few components as possible to get a
working compiler (<code>rustc</code>, <code>rust-std</code>, and <code>cargo</code>). It’s recommended to use
this component on Windows systems if you don’t use local documentation (the
large number of files can cause issues with some Antivirus systems), and in
CI.</li>
<li>The <strong>default</strong> profile includes all of components in the <strong>minimal</strong>
profile, and adds <code>rust-docs</code>, <code>rustfmt</code>, and <code>clippy</code>. This profile will be
used by <code>rustup</code> by default, and it’s the one recommended for general use.</li>
<li>The <strong>complete</strong> profile includes all the components available through
<code>rustup</code>. This should never be used, as it includes <em>every</em> component ever
included in the metadata and thus will almost always fail. If you are
looking for a way to install devtools such as <code>miri</code> or IDE integration
tools (<code>rust-analyzer</code>), you should use the <code>default</code> profile and
install the needed additional components manually, either by using <code>rustup component add</code> or by using <code>-c</code> when installing the toolchain.</li>
</ul>
<p>To change the profile <code>rustup install</code> uses by default, you can use the
<code>rustup set profile</code> command.
For example, to select the minimal profile you can use:</p>
<pre><code class="language-console">rustup set profile minimal
</code></pre>
<p>You can also directly select the profile used when installing a toolchain with:</p>
<pre><code class="language-console">rustup install --profile &lt;name&gt;
</code></pre>
<p>It’s also possible to choose the default profile when installing <code>rustup</code> for
the first time, either interactively by choosing the “Customize installation”
option or programmatically by passing the <code>--profile=&lt;name&gt;</code> flag. Profiles
will only affect newly installed toolchains: as usual it will be possible to
install individual components later with: <code>rustup component add</code>.</p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="proxies"><a class="header" href="#proxies">Proxies</a></h1>
<p><code>rustup</code> provides a number of wrappers for common Rust tools.
These are called <em>proxies</em> and represent commands which are
provided by the various <a href="#components">components</a>.</p>
<p>The list of proxies is currently static in <code>rustup</code> and is as follows:</p>
<ul>
<li>
<p><code>rustc</code> is the compiler for the Rust programming language, provided by the project itself and comes from the <code>rustc</code> component.</p>
</li>
<li>
<p><code>rustdoc</code> is a tool distributed in the <code>rustc</code> component which helps you to generate documentation for Rust projects.</p>
</li>
<li>
<p><code>cargo</code> is the Rust package manager which downloads your Rust package’s dependencies, compiles your packages, makes distributable packages, and uploads them to crates.io (the Rust community’s package registry). It comes from the <code>cargo</code> component.</p>
</li>
<li>
<p><code>rust-lldb</code>, <code>rust-gdb</code>, and <code>rust-gdbgui</code> are simple wrappers around the <code>lldb</code>, <code>gdb</code>, and <code>gdbgui</code> debuggers respectively. The wrappers enable some pretty-printing of Rust values and add some convenience features to the debuggers by means of their scripting interfaces.</p>
</li>
<li>
<p><code>rust-analyzer</code> is part of the Rust IDE integration tooling. It implements the language-server protocol to permit IDEs and editors such as Visual Studio Code, Vim, or Emacs, access to the semantics of the Rust code you are editing. It comes from the <code>rust-analyzer</code> component.</p>
</li>
<li>
<p><code>cargo-clippy</code> and <code>clippy-driver</code> are related to the <code>clippy</code> linting tool which provides extra checks for common mistakes and stylistic choices and it comes from the <code>clippy</code> component.</p>
</li>
<li>
<p><code>cargo-miri</code> is an experimental interpreter for Rust’s mid-level intermediate representation (MIR) and it comes from the <code>miri</code> component.</p>
</li>
<li>
<p><code>rls</code> is a deprecated IDE tool that has been replaced by <code>rust-analyzer</code>. It comes from the <code>rls</code> component.</p>
</li>
</ul>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="basic-usage"><a class="header" href="#basic-usage">Basic usage</a></h1>
<h2 id="keeping-rust-up-to-date"><a class="header" href="#keeping-rust-up-to-date">Keeping Rust up to date</a></h2>
<p>Rust is distributed on three different <a href="#channels">release channels</a>: stable, beta, and
nightly. <code>rustup</code> uses the stable channel by default, which
represents the latest release of Rust. Stable publishes new releases every six weeks.</p>
<p>When a new version of Rust is released, simply type <code>rustup update</code> to update:</p>
<pre><code class="language-console">$ rustup update
info: syncing channel updates for 'stable'
info: downloading component 'rustc'
info: downloading component 'rust-std'
info: downloading component 'rust-docs'
info: downloading component 'cargo'
info: installing component 'rustc'
info: installing component 'rust-std'
info: installing component 'rust-docs'
info: installing component 'cargo'
info: checking for self-update
info: downloading self-update
stable updated: rustc 1.7.0 (a5d1e7a59 2016-02-29)
</code></pre>
<h2 id="keeping-rustup-up-to-date"><a class="header" href="#keeping-rustup-up-to-date">Keeping <code>rustup</code> up to date</a></h2>
<p>If your <code>rustup</code> was built with the <a href="https://github.com/rust-lang/rustup/blob/HEAD/Cargo.toml#L29">no-self-update feature</a>, it can not update
itself. This is not the default, and only versions of <code>rustup</code> built with
<code>--no-default-features</code>, or obtained from a third-party distributor who has
disabled it (such as NixOS).</p>
<p>Otherwise Rustup can update itself. It is possible to control Rustup’s automatic
self update mechanism with the <code>auto-self-update</code> configuration variable. This
setting supports three values: <code>enable</code> and <code>disable</code> and <code>check-only</code>.</p>
<ul>
<li><code>disable</code> will ensure that no automatic self updating actions are taken.</li>
<li><code>enable</code> will mean that <code>rustup update</code> and similar commands will also check for, and install, any update to Rustup.</li>
<li><code>check-only</code> will cause any automatic self update to check and report on any updates, but not to automatically install them.</li>
</ul>
<p>Whether <code>auto-self-update</code> is <code>enable</code> or not, you can request that Rustup
update itself to the latest version of <code>rustup</code> by running <code>rustup self update</code>.
This will not download new toolchains:</p>
<pre><code class="language-console">$ rustup self update
info: checking for self-update
info: downloading self-update
</code></pre>
<h3 id="disabling-self-updates-on-a-per-invocation-basis"><a class="header" href="#disabling-self-updates-on-a-per-invocation-basis">Disabling self updates on a per-invocation basis</a></h3>
<blockquote>
<p>Self updates can also be suppressed on individual invocations of <code>rustup</code> by
passing the argument <code>--no-self-update</code> when running <code>rustup update</code> or
<code>rustup toolchain install</code>.</p>
</blockquote>
<h2 id="help-system"><a class="header" href="#help-system">Help system</a></h2>
<p>The <code>rustup</code> command-line has a built-in help system that provides more
information about each command. Run <code>rustup help</code> for an overview. Detailed
help for each subcommand is also available. For example, run <code>rustup toolchain install --help</code> for specifics on installing <a href="#toolchains">toolchains</a>.</p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="overrides"><a class="header" href="#overrides">Overrides</a></h1>
<p><code>rustup</code> automatically determines which <a href="#toolchains">toolchain</a> to use when one of the
installed commands like <code>rustc</code> is executed. There are several ways to control
and override which toolchain is used:</p>
<ol>
<li>A <a href="#toolchain-override-shorthand">toolchain override shorthand</a> used on the command-line, such as <code>cargo +beta</code>.</li>
<li>The <code>RUSTUP_TOOLCHAIN</code> environment variable.</li>
<li>A <a href="#directory-overrides">directory override</a>, set with the <code>rustup override</code> command.</li>
<li>The <a href="#the-toolchain-file"><code>rust-toolchain.toml</code></a> file.</li>
<li>The <a href="#default-toolchain">default toolchain</a>.</li>
</ol>
<p>The toolchain is chosen in the order listed above, using the first one that is
specified. There is one exception though: directory overrides and the
<code>rust-toolchain.toml</code> file are also preferred by their proximity to the current
directory. That is, these two override methods are discovered by walking up
the directory tree toward the filesystem root, and a <code>rust-toolchain.toml</code> file
that is closer to the current directory will be preferred over a directory
override that is further away.</p>
<p>To verify which toolchain is active, you can use <code>rustup show</code>.</p>
<h2 id="toolchain-override-shorthand"><a class="header" href="#toolchain-override-shorthand">Toolchain override shorthand</a></h2>
<p>The <code>rustup</code> toolchain proxies can be instructed directly to use a specific
toolchain, a convenience for developers who often test different toolchains.
If the first argument to <code>cargo</code>, <code>rustc</code> or other tools in the toolchain
begins with <code>+</code>, it will be interpreted as a <code>rustup</code> toolchain name, and that
toolchain will be preferred, as in</p>
<pre><code class="language-console">cargo +beta test
</code></pre>
<h2 id="directory-overrides"><a class="header" href="#directory-overrides">Directory overrides</a></h2>
<p>Directories can be assigned their own Rust toolchain with <code>rustup override</code>.
When a directory has an override then any time <code>rustc</code> or <code>cargo</code> is run
inside that directory, or one of its child directories, the override toolchain
will be invoked.</p>
<p>To use to a specific nightly for a directory:</p>
<pre><code class="language-console">rustup override set nightly-2014-12-18
</code></pre>
<p>Or a specific stable release:</p>
<pre><code class="language-console">rustup override set 1.0.0
</code></pre>
<p>To see the active toolchain use <code>rustup show</code>. To remove the override and use
the default toolchain again, <code>rustup override unset</code>.</p>
<p>The per-directory overrides are stored in <a href="#configuration">a configuration file</a> in <code>rustup</code>’s
home directory.</p>
<h2 id="the-toolchain-file"><a class="header" href="#the-toolchain-file">The toolchain file</a></h2>
<p>Some projects find themselves ‘pinned’ to a specific release of Rust and want
this information reflected in their source repository. This is most often the
case for nightly-only software that pins to a revision from the release
archives.</p>
<p>In these cases the toolchain can be named in the project’s directory in a file
called <code>rust-toolchain.toml</code> or <code>rust-toolchain</code>. If both files are present in
a directory, the latter is used for backwards compatibility. The files use the
<a href="https://toml.io/">TOML</a> format and have the following layout:</p>
<pre><code class="language-toml">[toolchain]
channel = "nightly-2020-07-10"
components = [ "rustfmt", "rustc-dev" ]
targets = [ "wasm32-unknown-unknown", "thumbv2-none-eabi" ]
profile = "minimal"
</code></pre>
<p>The <code>[toolchain]</code> section is mandatory, and at least one property must be
specified. <code>channel</code> and <code>path</code> are mutually exclusive.</p>
<p>For backwards compatibility, <code>rust-toolchain</code> files also support a legacy
format that only contains a toolchain name without any TOML encoding, e.g.
just <code>nightly-2021-01-21</code>. The file has to be encoded in US-ASCII in this case
(if you are on Windows, check the encoding and that it does not start with a
BOM). The legacy format is not available in <code>rust-toolchain.toml</code> files.</p>
<p>If you see the following error (when running <code>rustc</code>, <code>cargo</code> or other command)</p>
<pre><code>error: invalid channel name '[toolchain]' in '/PATH/TO/DIRECTORY/rust-toolchain'
</code></pre>
<p>it means you’re running <code>rustup</code> pre-1.23.0 and trying to interact with a project
that uses the new TOML encoding in the <code>rust-toolchain</code> file. You need to upgrade
<code>rustup</code> to 1.23.0+.</p>
<p>The <code>rust-toolchain.toml</code>/<code>rust-toolchain</code> files are suitable to check in to
source control. If that’s done, <code>Cargo.lock</code> should probably be tracked too if
the toolchain is pinned to a specific release, to avoid potential compatibility
issues with dependencies.</p>
<h3 id="toolchain-file-settings"><a class="header" href="#toolchain-file-settings">Toolchain file settings</a></h3>
<h4 id="channel"><a class="header" href="#channel">channel</a></h4>
<p>The <code>channel</code> setting specifies which <a href="#toolchains">toolchain</a> to use. The value is a
string in the following form:</p>
<pre><code>(&lt;channel&gt;[-&lt;date&gt;])|&lt;custom toolchain name&gt;
&lt;channel&gt; = stable|beta|nightly|&lt;versioned&gt;[-&lt;prerelease&gt;]
&lt;versioned&gt; = &lt;major.minor&gt;|&lt;major.minor.patch&gt;
&lt;prerelease&gt; = beta[.&lt;number&gt;]
&lt;date&gt; = YYYY-MM-DD
</code></pre>
<h4 id="path"><a class="header" href="#path">path</a></h4>
<p>The <code>path</code> setting allows a custom toolchain to be used. The value is an
absolute path string.</p>
<p>Since a <code>path</code> directive directly names a local toolchain, other options
like <code>components</code>, <code>targets</code>, and <code>profile</code> have no effect.</p>
<p><code>channel</code> and <code>path</code> are mutually exclusive, since a <code>path</code> already
points to a specific toolchain.</p>
<h4 id="profile"><a class="header" href="#profile">profile</a></h4>
<p>The <code>profile</code> setting names a group of components to be installed. The
value is a string. The valid options are: <code>minimal</code>, <code>default</code>, and
<code>complete</code>. See <a href="#profiles">profiles</a> for details of each.</p>
<p>Note that if not specified, the <code>default</code> profile is not necessarily
used, as a different default profile might have been set with <code>rustup set profile</code>.</p>
<h4 id="components-1"><a class="header" href="#components-1">components</a></h4>
<p>The <code>components</code> setting contains a list of additional components to
install. The value is a list of strings. See <a href="#components">components</a> for a list of
components. Note that different toolchains may have different components
available.</p>
<p>The components listed here are additive with the current profile.</p>
<h4 id="targets"><a class="header" href="#targets">targets</a></h4>
<p>The <code>targets</code> setting contains a list of platforms to install for
<a href="https://rust-lang.github.io/rustup/cross-compilation.html">cross-compilation</a>. The value is a list of strings.</p>
<p>The host platform is automatically included; the targets listed here are
additive.</p>
<h2 id="default-toolchain"><a class="header" href="#default-toolchain">Default toolchain</a></h2>
<p>If no other overrides are set, the global default toolchain will be used. This
default can be chosen when <code>rustup</code> is <a href="#installation">installed</a>. The <code>rustup default</code>
command can be used to set and query the current default. Run <code>rustup default</code>
without any arguments to print the current default. Specify a toolchain as an
argument to change the default:</p>
<pre><code class="language-console">rustup default nightly-2020-07-27
</code></pre>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="cross-compilation"><a class="header" href="#cross-compilation">Cross-compilation</a></h1>
<p>Rust <a href="https://doc.rust-lang.org/nightly/rustc/platform-support.html">supports a great number of platforms</a>. For many of these platforms
The Rust Project publishes binary releases of the standard library, and for
some the full compiler. <code>rustup</code> gives easy access to all of them.</p>
<p>When you first install a toolchain, <code>rustup</code> installs only the standard
library for your <em>host</em> platform - that is, the architecture and operating
system you are presently running. To compile to other platforms you must
install other <em>target</em> platforms. This is done with the <code>rustup target add</code>
command. For example, to add the Android target:</p>
<pre><code class="language-console">$ rustup target add arm-linux-androideabi
info: downloading component 'rust-std' for 'arm-linux-androideabi'
info: installing component 'rust-std' for 'arm-linux-androideabi'
</code></pre>
<p>With the <code>arm-linux-androideabi</code> target installed you can then build for
Android with Cargo by passing the <code>--target</code> flag, as in <code>cargo build --target=arm-linux-androideabi</code>.</p>
<p>Note that <code>rustup target add</code> only installs the Rust standard library for a
given target. There are typically other tools necessary to cross-compile,
particularly a linker. For example, to cross compile to Android the <a href="https://developer.android.com/tools/sdk/ndk/index.html">Android
NDK</a> must be installed. In the future, <code>rustup</code> will provide assistance
installing the NDK components as well. See the <a href="https://doc.rust-lang.org/cargo/reference/config.html#target">target section</a> of the
<code>cargo</code> configuration for how to setup a linker to use for a certain target.</p>
<p>To install a target for a toolchain that isn’t the default toolchain use the
<code>--toolchain</code> argument of <code>rustup target add</code>, like so:</p>
<pre><code class="language-console">$ rustup target add --toolchain &lt;toolchain&gt; &lt;target&gt;...
</code></pre>
<p>To see a list of available targets, <code>rustup target list</code>. To remove a
previously-added target, <code>rustup target remove</code>.</p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="environment-variables"><a class="header" href="#environment-variables">Environment variables</a></h1>
<ul>
<li>
<p><code>RUSTUP_LOG</code> (default: none). Enables Rustup’s “custom logging mode”. In this mode,
the verbosity of Rustup’s log lines can be specified with <code>tracing_subscriber</code>’s
<a href="https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives">directive syntax</a>. For example, set <code>RUSTUP_LOG=rustup=DEBUG</code> to receive log lines
from <code>rustup</code> itself with a maximal verbosity of <code>DEBUG</code>.</p>
</li>
<li>
<p><code>RUSTUP_HOME</code> (default: <code>~/.rustup</code> or <code>%USERPROFILE%/.rustup</code>). Sets the
root <code>rustup</code> folder, used for storing installed toolchains and
configuration options.</p>
</li>
<li>
<p><code>RUSTUP_TOOLCHAIN</code> (default: none). If set, will <a href="#overrides">override</a> the toolchain used
for all rust tool invocations. A toolchain with this name should be installed,
or invocations will fail. This can specify custom toolchains, installable
toolchains, or the absolute path to a toolchain.</p>
</li>
<li>
<p><code>RUSTUP_DIST_SERVER</code> (default: <code>https://static.rust-lang.org</code>). Sets the root
URL for downloading static resources related to Rust. You can change this to
instead use a local mirror, or to test the binaries from the staging
directory.</p>
</li>
<li>
<p><del><code>RUSTUP_DIST_ROOT</code></del> <em>deprecated</em> (default: <code>https://static.rust-lang.org/dist</code>).
Use <code>RUSTUP_DIST_SERVER</code> instead.</p>
</li>
<li>
<p><code>RUSTUP_UPDATE_ROOT</code> (default <code>https://static.rust-lang.org/rustup</code>). Sets
the root URL for downloading self-update.</p>
</li>
<li>
<p><code>RUSTUP_VERSION</code> (default: none). Overrides the rustup version (e.g. <code>1.27.1</code>)
to be downloaded when executing <code>rustup-init.sh</code> or <code>rustup self update</code>.</p>
</li>
<li>
<p><code>RUSTUP_IO_THREADS</code> <em>unstable</em> (default: reported cpu count, max 8). Sets the
number of threads to perform close IO in. Set to <code>1</code> to force
single-threaded IO for troubleshooting, or an arbitrary number to override
automatic detection.</p>
</li>
<li>
<p><code>RUSTUP_TRACE_DIR</code> <em>unstable</em> (default: no tracing). Enables tracing and
determines the directory that traces will be written too. Traces are of the
form PID.trace. Traces can be read by the Catapult project <a href="https://github.com/catapult-project/catapult/blob/master/tracing/README.md">tracing viewer</a>.</p>
</li>
<li>
<p><code>RUSTUP_TERM_COLOR</code> (default: <code>auto</code>). Controls whether colored output is used in the terminal.
Set to <code>auto</code> to use colors only in tty streams, to <code>always</code> to always enable colors,
or to <code>never</code> to disable colors.</p>
</li>
<li>
<p><code>RUSTUP_UNPACK_RAM</code> <em>unstable</em> (default: free memory or 500MiB if unable to tell, min 210MiB). Caps the amount of
RAM (in bytes) <code>rustup</code> will use for IO tasks while unpacking.</p>
</li>
<li>
<p><code>RUSTUP_NO_BACKTRACE</code>. Disables backtraces on non-panic errors even when
<code>RUST_BACKTRACE</code> is set.</p>
</li>
<li>
<p><code>RUSTUP_PERMIT_COPY_RENAME</code> <em>unstable</em>. When set, allows rustup to fall-back
to copying files if attempts to <code>rename</code> result in cross-device link
errors. These errors occur on OverlayFS, which is used by <a href="https://docs.docker.com/storage/storagedriver/overlayfs-driver/#modifying-files-or-directories">Docker</a>. This
feature sacrifices some transactions protections and may be removed at any
point. Linux only.</p>
</li>
<li>
<p><code>RUSTUP_AUTO_INSTALL</code> (default: 1) When set to <code>1</code>, installs the active
toolchain when it is absent. Set this value to <code>0</code> to disable automatic
installation.</p>
</li>
<li>
<p><code>RUSTUP_HARDLINK_PROXIES</code> <em>unstable</em>. When set, rustup will not attempt to
symlink proxies and instead always use hardlinks. If you find this fixes
a problem, then please report the issue on the <a href="https://github.com/rust-lang/rustup/issues">rustup issue tracker</a>.</p>
</li>
<li>
<p><code>RUSTUP_TERM_PROGRESS_WHEN</code> (default: <code>auto</code>). Controls whether progress bars are shown or not.
Set to <code>always</code> to always enable progress bars, and to <code>never</code> to disable them.</p>
</li>
<li>
<p><code>RUSTUP_TERM_WIDTH</code> (default: none). Allows to override the terminal width for progress bars.</p>
</li>
<li>
<p><code>RUSTUP_DOWNLOAD_TIMEOUT</code> <em>unstable</em> (default: 180). Allows to override the default
timeout (in seconds) for downloading components.</p>
</li>
<li>
<p><code>RUSTUP_CONCURRENT_DOWNLOADS</code> <em>unstable</em> (default: 2). Controls the number of
downloads made concurrently.</p>
</li>
<li>
<p><code>RUSTUP_TOOLCHAIN_SOURCE</code> <em>unstable</em>. Set by rustup to tell proxied tools how <code>RUSTUP_TOOLCHAIN</code> was determined. Non-rustup tools should not set this environment variable, except insofar as to mirror an earlier invocation from rustup.</p>
</li>
</ul>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="configuration"><a class="header" href="#configuration">Configuration</a></h1>
<p>Rustup has a <a href="https://github.com/toml-lang/toml">TOML</a> settings file at
<code>${RUSTUP_HOME}/settings.toml</code> (which defaults to <code>~/.rustup</code> or
<code>%USERPROFILE%/.rustup</code>). The schema for this file is not part of the public
interface for rustup - the rustup CLI should be used to query and set settings.</p>
<p>On Unix operating systems a fallback settings file is consulted for some
settings. This fallback file is located at <code>/etc/rustup/settings.toml</code> and
currently can define only <code>default_toolchain</code>.</p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="network-proxies"><a class="header" href="#network-proxies">Network proxies</a></h1>
<p>Enterprise networks often don’t have direct outside HTTP access, but enforce
the use of proxies. If you’re on such a network, you can request that <code>rustup</code>
uses a proxy by setting its URL in the environment. In most cases, setting
<code>https_proxy</code> should be sufficient. Commands may differ between different
systems and shells:</p>
<ul>
<li>On a Unix-like system with a shell like <strong>bash</strong> or <strong>zsh</strong>:
<pre><code class="language-bash">export https_proxy=socks5://proxy.example.com:1080
</code></pre>
</li>
<li>On Windows <a href="https://en.wikipedia.org/wiki/Cmd.exe"><strong>Command Prompt (cmd)</strong></a>:
<pre><code class="language-cmd">set https_proxy=socks5://proxy.example.com:1080
</code></pre>
</li>
<li>On Windows <a href="https://en.wikipedia.org/wiki/PowerShell"><strong>PowerShell</strong></a> (or <strong>PowerShell Core</strong>):
<pre><code class="language-cmd">$env:https_proxy="socks5://proxy.example.com:1080"
</code></pre>
</li>
<li>Replace <code>socks5://proxy.example.com:1080</code> with
<code>http://proxy.example.com:8080</code> when an HTTP proxy is used instead.</li>
</ul>
<p>If you need a more complex setup, <code>rustup</code> supports the convention used by the
<strong>curl</strong> program, documented in the ENVIRONMENT section of <a href="https://curl.se/docs/manpage.html#:~:text=Environment,-The%20environment%20variables">its manual
page</a>.</p>
<p>The use of <code>curl</code> is presently <strong>deprecated</strong>, however it can still be used by
providing the <code>RUSTUP_USE_CURL</code> environment variable, for example:</p>
<pre><code class="language-bash">RUSTUP_USE_CURL=1 rustup update
</code></pre>
<p>Note that some versions of <code>libcurl</code> apparently require you to drop the
<code>http://</code> or <code>https://</code> prefix in environment variables. For example, <code>export http_proxy=proxy.example.com:1080</code> (and likewise for HTTPS). If you are
getting an SSL <code>unknown protocol</code> error from <code>rustup</code> via <code>libcurl</code> but the
command-line <code>curl</code> command works fine, this may be the problem.</p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="examples"><a class="header" href="#examples">Examples</a></h1>
<div class="table-wrapper">
<table>
<thead>
<tr><th>Command</th><th>Description</th></tr>
</thead>
<tbody>
<tr><td><code>rustup default nightly</code></td><td>Set the <a href="#default-toolchain">default toolchain</a> to the latest nightly</td></tr>
<tr><td><code>rustup set profile minimal</code></td><td>Set the default <a href="#profiles">profile</a></td></tr>
<tr><td><code>rustup target list</code></td><td>List all available <a href="#cross-compilation">targets</a> for the active toolchain</td></tr>
<tr><td><code>rustup target add arm-linux-androideabi</code></td><td>Install the Android target</td></tr>
<tr><td><code>rustup target remove arm-linux-androideabi</code></td><td>Remove the Android target</td></tr>
<tr><td><code>rustup run nightly rustc foo.rs</code></td><td>Run the nightly regardless of the active toolchain</td></tr>
<tr><td><code>rustc +nightly foo.rs</code></td><td><a href="#toolchain-override-shorthand">Shorthand</a> way to run a nightly compiler</td></tr>
<tr><td><code>rustup run nightly bash</code></td><td>Run a shell configured for the nightly compiler</td></tr>
<tr><td><code>rustup default stable-msvc</code></td><td>On Windows, use the MSVC toolchain instead of GNU</td></tr>
<tr><td><code>rustup override set nightly-2015-04-01</code></td><td>For the current directory, use a nightly from a specific date</td></tr>
<tr><td><code>rustup toolchain link my-toolchain "C:\RustInstallation"</code></td><td>Install a custom toolchain by symlinking an existing installation</td></tr>
<tr><td><code>rustup show</code></td><td>Show which toolchain will be used in the current directory</td></tr>
<tr><td><code>rustup toolchain uninstall nightly</code></td><td>Uninstall a given toolchain</td></tr>
<tr><td><code>rustup toolchain help</code></td><td>Show the <code>help</code> page for a subcommand (like <code>toolchain</code>)</td></tr>
<tr><td><code>rustup man cargo</code></td><td>(<em>Unix only</em>) View the man page for a given command (like <code>cargo</code>)</td></tr>
</tbody>
</table>
</div>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="security"><a class="header" href="#security">Security</a></h1>
<p><code>rustup</code> is secure enough for most people, but it <a href="https://github.com/rust-lang/rustup/issues?q=is%3Aopen+is%3Aissue+label%3Asecurity">still needs work</a>.
<code>rustup</code> performs all downloads over HTTPS, but does not yet validate
signatures of downloads.</p>
<p>File modes on installation honor umask as of 1.18.4, use umask if very tight
controls are desired.</p>
<p>If you wish to report a security issue, please follow the <a href="https://www.rust-lang.org/policies/security">Rust security
policy</a>.</p>
<div style="break-before: page; page-break-before: always;"></div>
<h1 id="faq"><a class="header" href="#faq">FAQ</a></h1>
<h3 id="is-this-an-official-rust-project"><a class="header" href="#is-this-an-official-rust-project">Is this an official Rust project?</a></h3>
<p>Yes. rustup is an official Rust project. It is the recommended way to install
Rust at https://www.rust-lang.org.</p>
<h3 id="how-is-this-related-to-multirust"><a class="header" href="#how-is-this-related-to-multirust">How is this related to multirust?</a></h3>
<p>rustup is the successor to <a href="https://github.com/brson/multirust">multirust</a>. rustup began as multirust-rs, a
rewrite of multirust from shell script to Rust, by <a href="https://github.com/Diggsey">Diggory Blake</a>, and is now
maintained by The Rust Project.</p>
<h3 id="can-rustup-download-the-rust-source-code"><a class="header" href="#can-rustup-download-the-rust-source-code">Can rustup download the Rust source code?</a></h3>
<p>The source for Rust’s standard library can be obtained by running <code>rustup component add rust-src</code>. It will be downloaded to the <code>&lt;toolchain root&gt;/lib/rustlib/src/rust</code> directory of the current toolchain.</p>
<p>The source for the compiler and tools must be obtained from the <a href="https://github.com/rust-lang/rust/">Rust
repository</a> or the standalone <a href="https://forge.rust-lang.org/infra/other-installation-methods.html#source-code">source tarballs</a>.</p>
<h3 id="rustup-fails-with-windows-error-32"><a class="header" href="#rustup-fails-with-windows-error-32">rustup fails with Windows error 32</a></h3>
<p>If <code>rustup</code> fails with Windows error 32, it may be due to antivirus scanning
in the background. Disable antivirus scanner and try again.</p>
<h3 id="i-get-error-could-not-remove-rustup-bin-file-cusersusercargobinrustupexe"><a class="header" href="#i-get-error-could-not-remove-rustup-bin-file-cusersusercargobinrustupexe">I get “error: could not remove ‘rustup-bin’ file: ‘C:\Users\USER\.cargo\bin\rustup.exe’”</a></h3>
<p>If <code>rustup</code> fails to self-update in this way it’s usually because RLS is
running (your editor is open and running RLS). The solution is to stop RLS (by
closing your editor) and try again.</p>
<h3 id="rustup-exited-successfully-but-i-cant-run-rustc---version"><a class="header" href="#rustup-exited-successfully-but-i-cant-run-rustc---version">rustup exited successfully but I can’t run <code>rustc --version</code></a></h3>
<p>Restart your shell. This will reload your <code>PATH</code> environment
variable to include Cargo’s bin directory (<code>$CARGO_HOME/bin</code>).</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
</nav>
</div>
<template id=fa-eye><span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M288 32c-80.8 0-145.5 36.8-192.6 80.6C48.6 156 17.3 208 2.5 243.7c-3.3 7.9-3.3 16.7 0 24.6C17.3 304 48.6 356 95.4 399.4C142.5 443.2 207.2 480 288 480s145.5-36.8 192.6-80.6c46.8-43.5 78.1-95.4 93-131.1c3.3-7.9 3.3-16.7 0-24.6c-14.9-35.7-46.2-87.7-93-131.1C433.5 68.8 368.8 32 288 32zM432 256c0 79.5-64.5 144-144 144s-144-64.5-144-144s64.5-144 144-144s144 64.5 144 144zM288 192c0 35.3-28.7 64-64 64c-11.5 0-22.3-3-31.6-8.4c-.2 2.8-.4 5.5-.4 8.4c0 53 43 96 96 96s96-43 96-96s-43-96-96-96c-2.8 0-5.6 .1-8.4 .4c5.3 9.3 8.4 20.1 8.4 31.6z"/></svg></span></template>
<template id=fa-eye-slash><span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M38.8 5.1C28.4-3.1 13.3-1.2 5.1 9.2S-1.2 34.7 9.2 42.9l592 464c10.4 8.2 25.5 6.3 33.7-4.1s6.3-25.5-4.1-33.7L525.6 386.7c39.6-40.6 66.4-86.1 79.9-118.4c3.3-7.9 3.3-16.7 0-24.6c-14.9-35.7-46.2-87.7-93-131.1C465.5 68.8 400.8 32 320 32c-68.2 0-125 26.3-169.3 60.8L38.8 5.1zM223.1 149.5C248.6 126.2 282.7 112 320 112c79.5 0 144 64.5 144 144c0 24.9-6.3 48.3-17.4 68.7L408 294.5c5.2-11.8 8-24.8 8-38.5c0-53-43-96-96-96c-2.8 0-5.6 .1-8.4 .4c5.3 9.3 8.4 20.1 8.4 31.6c0 10.2-2.4 19.8-6.6 28.3l-90.3-70.8zm223.1 298L373 389.9c-16.4 6.5-34.3 10.1-53 10.1c-79.5 0-144-64.5-144-144c0-6.9 .5-13.6 1.4-20.2L83.1 161.5C60.3 191.2 44 220.8 34.5 243.7c-3.3 7.9-3.3 16.7 0 24.6c14.9 35.7 46.2 87.7 93 131.1C174.5 443.2 239.2 480 320 480c47.8 0 89.9-12.9 126.2-32.5z"/></svg></span></template>
<template id=fa-copy><span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M502.6 70.63l-61.25-61.25C435.4 3.371 427.2 0 418.7 0H255.1c-35.35 0-64 28.66-64 64l.0195 256C192 355.4 220.7 384 256 384h192c35.2 0 64-28.8 64-64V93.25C512 84.77 508.6 76.63 502.6 70.63zM464 320c0 8.836-7.164 16-16 16H255.1c-8.838 0-16-7.164-16-16L239.1 64.13c0-8.836 7.164-16 16-16h128L384 96c0 17.67 14.33 32 32 32h47.1V320zM272 448c0 8.836-7.164 16-16 16H63.1c-8.838 0-16-7.164-16-16L47.98 192.1c0-8.836 7.164-16 16-16H160V128H63.99c-35.35 0-64 28.65-64 64l.0098 256C.002 483.3 28.66 512 64 512h192c35.2 0 64-28.8 64-64v-32h-47.1L272 448z"/></svg></span></template>
<template id=fa-play><span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 384 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M73 39c-14.8-9.1-33.4-9.4-48.5-.9S0 62.6 0 80V432c0 17.4 9.4 33.4 24.5 41.9s33.7 8.1 48.5-.9L361 297c14.3-8.7 23-24.2 23-41s-8.7-32.2-23-41L73 39z"/></svg></span></template>
<template id=fa-clock-rotate-left><span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M75 75L41 41C25.9 25.9 0 36.6 0 57.9V168c0 13.3 10.7 24 24 24H134.1c21.4 0 32.1-25.9 17-41l-30.8-30.8C155 85.5 203 64 256 64c106 0 192 86 192 192s-86 192-192 192c-40.8 0-78.6-12.7-109.7-34.4c-14.5-10.1-34.4-6.6-44.6 7.9s-6.6 34.4 7.9 44.6C151.2 495 201.7 512 256 512c141.4 0 256-114.6 256-256S397.4 0 256 0C185.3 0 121.3 28.7 75 75zm181 53c-13.3 0-24 10.7-24 24V256c0 6.4 2.5 12.5 7 17l72 72c9.4 9.4 24.6 9.4 33.9 0s9.4-24.6 0-33.9l-65-65V152c0-13.3-10.7-24-24-24z"/></svg></span></template>
<script>
window.playground_copyable = true;
</script>
<script src="elasticlunr-ef4e11c1.min.js"></script>
<script src="mark-09e88c2c.min.js"></script>
<script src="searcher-c2a407aa.js"></script>
<script src="clipboard-1626706a.min.js"></script>
<script src="highlight-abc7f01d.js"></script>
<script src="book-a0b12cfe.js"></script>
<!-- Custom JS scripts -->
<script>
window.addEventListener('load', function() {
window.setTimeout(window.print, 100);
});
</script>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink