Rust target folders and the Cargo cache: reclaim disk space

Part of: Mac disk cleanup for developers: every cache, what it costs to rebuild (Developers)

A Rust target folder holds compiled output, and it gets large because Cargo keeps output for every dependency and build type. You can preview what a clean removes with cargo clean -n, then remove it. The cost is a full rebuild of that project.

Cargo is Rust’s build tool. target sits next to a project’s Cargo.toml. Each project has its own.

See how big it is

From inside a project:

du -sh target
cargo clean -n

The first prints the size. The second is a dry run: the -n flag, short for --dry-run, lists what would be deleted and changes nothing. By default it prints a short summary rather than a list of files, and says nothing was deleted. Add --verbose to see the paths. We ran it in a throwaway project with Cargo 1.90.0: it printed a one-line summary (file count and total size) and a warning that no files were deleted. Output can differ between Cargo versions, and older versions may not have the flag, so check cargo clean --help on yours. Running cargo clean itself (without -n) was not tried for this article.

To find the folders across all your projects:

find ~/Projects -maxdepth 4 -name target -type d -prune

Change ~/Projects to where your code lives. The name target is also used by other tools such as Maven, so check that a Cargo.toml is next to each result before you delete anything.

Why it gets so big

Cargo keeps compiled code for every dependency in both debug and release modes, plus incremental data that speeds up rebuilds, and it does not remove old output on its own. Debug information is a large share of a debug build. Many small projects each carry a full copy of their dependencies’ output, so ten projects can mean ten copies.

The Cargo cache in your home folder

Separate from target, Cargo keeps downloads in ~/.cargo:

• ~/.cargo/registry: downloaded crates, which are Rust libraries, from the crates.io registry.
• ~/.cargo/git: dependencies fetched straight from Git repositories.
• ~/.cargo/bin: programs you installed with Cargo. This is not a cache.

Check sizes with du -sh ~/.cargo/registry ~/.cargo/git. On the Mac used to check this article, the registry was larger than the Git folder.

Safe, risky, never

• Safe: target in projects you are not working on, and the crates in ~/.cargo/registry. Cost: a full rebuild for target, a download for the registry.
• Risky: target for a very large project or one on a slow machine, where a rebuild takes a long time. Also risky: clearing ~/.cargo/registry when you are offline.
• Never: do not delete ~/.cargo/bin, or the whole .cargo folder, to get space back. That removes programs you installed, such as rustfmt and any tools you added, and your config.

What a rebuild costs

The first build after a clean compiles every dependency again. For a small project that takes seconds. For a large one it can take many minutes. Rust compiles are CPU-heavy, so a laptop on battery feels it. The registry is cheaper: it only costs a download.

A way to keep the cost down is to clean only the older projects, and leave target for the ones you build daily. Another is to share one build folder between projects by setting a CARGO_TARGET_DIR path. That makes output reusable across projects, but also means one clean affects all of them. Treat it as an advanced option.

How to clean

1. Quit anything that is building, including editors with rust-analyzer running a check.
2. In the project folder, run cargo clean -n to preview.
3. Run the same command without -n to remove it, or move target to the Trash in Finder and empty the Trash. See why the Trash does not free space.
4. Build the project when you next work on it.

Similar patterns elsewhere

JavaScript projects have the same pattern in node_modules. See finding every node_modules folder. Go has its own module cache, covered in the Go module guide. The whole list is in the developer cleanup guide.

Worked example: look before you clean

The dry run is the safest habit in this article. From a project folder, run:

cargo clean -n

By default the output is a summary, and paths appear only with --verbose. We ran it in a throwaway project with Cargo 1.90.0 and it deleted nothing; the flag may be missing in older versions, and we did not run it on your kind of project. Check cargo clean --help first. Read the summary, or use du -sh target for the size. If it is small, skip the clean. If it is over a gigabyte, decide whether you will build that project soon.

Cargo’s home folder is also readable:

ls ~/.cargo

On the Mac used to check this article, it listed bin, git, registry, a config.toml file and a few other items. The bin folder and config.toml are yours. The registry and git folders are the cache.

Keep one build mode, drop the other

Cargo builds in two modes. The target folder has a debug folder and, once you build with the release option, a release folder. If you only need one, move just the other subfolder to the Trash instead of the whole target. Check the sizes first with du -sh target/*. The next build of the removed mode compiles again, and the other mode is untouched.

If something goes wrong

• The build fails after a clean with a network error. Cargo is fetching crates again and you are offline. Reconnect.
• A tool you installed with Cargo stopped working. You removed something in ~/.cargo/bin. Install the tool again.
• find lists a target folder that is not Rust. Maven uses the same name. Check for Cargo.toml first.
• Rebuilds are slow every time. If you set a shared CARGO_TARGET_DIR, another project may be cleaning or overwriting the same output.

When not to clean

Do not clean a project mid-deadline if its build takes many minutes. Do not clean when a build depends on a crate that is no longer published, since your cache may hold the only copy. Check first.

See sizes in a scan

DiskJoy is our product. Its scan reads your disk and lists large folders, including build folders such as target, without changing anything. Cleanup is not built yet, so DiskJoy does not remove them today.