<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>crates/home/README.md - fork/cargo @ home-0.5.12</title>
<meta name="description" content="crates/home/README.md in fork/cargo at home-0.5.12.">
<meta property="og:title" content="crates/home/README.md - fork/cargo @ home-0.5.12">
<meta property="og:description" content="crates/home/README.md in fork/cargo at home-0.5.12.">
<meta property="og:type" content="website">
<meta property="og:site_name" content="git.julia.blue">
<link rel="stylesheet" href="/css/style.css?v=62">
<script type="module" src="/js/main.js?v=62"></script>
</head>
<body>
<main data-ref="home-0.5.12" data-tip="4f15cc8882fb34bf70c945e9c8ae91d6c8c91757">
<noscript>
  <div class="callout">
    <p>
      hey! this is a static git repo viewer. commit diffs, file history,
      older commits and other revisions won't load without javascript.
    </p>
    <p>
      you are still able to view source files on branch/tag tips,
      but the experience is degraded.
    </p>
  </div>
</noscript>
<header class="repo"><div>
<h1>fork/cargo</h1>
</div>
<pre class="clone">git clone https://git.julia.blue/fork/cargo</pre>
</header>
<p class="snapshot-commit"><span class="commit-author">Ed Page</span><span class="commit-message" data-commit="c7a2aa3f8fb28dc36377d9bd6595faeb24f692dc">docs: update version notice for deprecation removal (#15511)</span><span class="snapshot-sha sha" data-commit="c7a2aa3f8fb28dc36377d9bd6595faeb24f692dc">c7a2aa3f8</span><time datetime="2025-05-09T14:10:33+00:00" title="2025-05-09 14:10:33 +0000">2025-05-09</time></p>
<header class="topbar"><details class="switcher"><summary>home-0.5.12</summary><div class="menu"><strong>branches</strong><a href="/fork/cargo/ref/master/">master</a><strong>tags</strong><a href="/fork/cargo/ref/0.87.0/">0.87.0</a><a href="/fork/cargo/ref/0.88.0/">0.88.0</a><a href="/fork/cargo/ref/0.89.0/">0.89.0</a><a href="/fork/cargo/ref/0.90.0/">0.90.0</a><a href="/fork/cargo/ref/0.91.0/">0.91.0</a><a href="/fork/cargo/ref/0.92.0/">0.92.0</a><a href="/fork/cargo/ref/0.93.0/">0.93.0</a><a class="current" href="/fork/cargo/ref/home-0.5.12/">home-0.5.12</a><a class="all" href="/fork/cargo/refs">all refs →</a></div></details><nav class="crumbs"><a href="/fork/cargo/">cargo</a> / <a href="/fork/cargo/ref/home-0.5.12/tree/crates/">crates</a> / <a href="/fork/cargo/ref/home-0.5.12/tree/crates/home/">home</a> / <span class="cur">README.md</span></nav>
<span class="view-stats"><span>1.7 KiB</span><span>38 lines</span></span><span class="actions"><a class="raw" href="/fork/cargo/raw/0211b5a0cd98a3984a76f796575816ea386042dc/crates/home/README.md">raw</a></span></header>
<div class="markdown-view"><input type="radio" name="markdown-view" id="markdown-rendered" checked><label for="markdown-rendered">rendered</label><input type="radio" name="markdown-view" id="markdown-code"><label for="markdown-code">code</label><section class="readme rendered"><p><a href="https://docs.rs/home"><img src="https://docs.rs/home/badge.svg" alt="Documentation" /></a>
<a href="https://crates.io/crates/home"><img src="https://img.shields.io/crates/v/home.svg" alt="crates.io" /></a></p>
<p>Canonical definitions of <code>home_dir</code>, <code>cargo_home</code>, and <code>rustup_home</code>.</p>
<p>This provides the definition of <code>home_dir</code> used by Cargo and rustup,
as well functions to find the correct value of <code>CARGO_HOME</code> and
<code>RUSTUP_HOME</code>.</p>
<p>The definition of <a href="https://doc.rust-lang.org/nightly/std/env/fn.home_dir.html"><code>home_dir</code></a> provided by the standard library is
incorrect because it considers the <code>HOME</code> environment variable on
Windows. This causes surprising situations where a Rust program will
behave differently depending on whether it is run under a Unix
emulation environment like Cygwin or MinGW. Neither Cargo nor rustup
use the standard library's definition - they use the definition here.</p>
<p><strong>Note:</strong> This has been fixed in Rust 1.85 to no longer use the <code>HOME</code>
environment variable on Windows. If you are still using this crate for the
purpose of getting a home directory, you are strongly encouraged to switch to
using the standard library's <a href="https://doc.rust-lang.org/nightly/std/env/fn.home_dir.html"><code>home_dir</code></a> instead. It is planned to have the
deprecation notice removed in 1.87.</p>
<p>This crate further provides two functions, <code>cargo_home</code> and
<code>rustup_home</code>, which are the canonical way to determine the location
that Cargo and rustup store their data.</p>
<p>See <a href="https://github.com/rust-lang/rust/issues/43321">rust-lang/rust#43321</a>.</p>
<blockquote>
<p>This crate is maintained by the Cargo team, primarily for use by Cargo and Rustup
and not intended for external use. This
crate may make major changes to its APIs or be deprecated without warning.</p>
</blockquote>
<h2>License</h2>
<p>MIT OR Apache-2.0</p>
</section><div class="code-panel"><pre class="code src language-markdown"><span class="code-line"><a class="ln" id="L1" href="#L1">1</a><span class="code-text">[![Documentation](https://docs.rs/home/badge.svg)](https://docs.rs/home)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2" href="#L2">2</a><span class="code-text">[![crates.io](https://img.shields.io/crates/v/home.svg)](https://crates.io/crates/home)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L3" href="#L3">3</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text">Canonical definitions of `home_dir`, `cargo_home`, and `rustup_home`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text">This provides the definition of `home_dir` used by Cargo and rustup,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text">as well functions to find the correct value of `CARGO_HOME` and</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text">`RUSTUP_HOME`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text">The definition of [`home_dir`] provided by the standard library is</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text">incorrect because it considers the `HOME` environment variable on</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text">Windows. This causes surprising situations where a Rust program will</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text">behave differently depending on whether it is run under a Unix</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text">emulation environment like Cygwin or MinGW. Neither Cargo nor rustup</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text">use the standard library&#39;s definition - they use the definition here.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L17" href="#L17">17</a><span class="code-text">**Note:** This has been fixed in Rust 1.85 to no longer use the `HOME`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text">environment variable on Windows. If you are still using this crate for the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text">purpose of getting a home directory, you are strongly encouraged to switch to</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text">using the standard library&#39;s [`home_dir`] instead. It is planned to have the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text">deprecation notice removed in 1.87.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text">This crate further provides two functions, `cargo_home` and</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L24" href="#L24">24</a><span class="code-text">`rustup_home`, which are the canonical way to determine the location</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text">that Cargo and rustup store their data.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text">See [rust-lang/rust#43321].</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text"><a-p>&gt; </a-p>This crate is maintained by the Cargo team, primarily for use by Cargo and Rustup</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text"><a-p>&gt; </a-p>and not intended for external use. This</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text"><a-p>&gt; </a-p>crate may make major changes to its APIs or be deprecated without warning.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L32" href="#L32">32</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L33" href="#L33">33</a><span class="code-text"><a-tu>[rust-lang/rust#43321]</a-tu>: <a-tu>https://github.com/rust-lang/rust/issues/43321</a-tu></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L34" href="#L34">34</a><span class="code-text"><a-tu>[`home_dir`]</a-tu>: <a-tu>https://doc.rust-lang.org/nightly/std/env/fn.home_dir.html</a-tu></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text"><a-p>##</a-p> <a-tt>License</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L37" href="#L37">37</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L38" href="#L38">38</a><span class="code-text">MIT OR Apache-2.0</span></span></pre></div></div>
</main>
</body>
</html>
