self-replace

self-replace is a Rust utility crate for building executables that can replace themselves with a newer version or delete themselves entirely at runtime. On Unix this is straightforward, but on Windows — where a running executable cannot simply overwrite or unlink its own file — the crate implements the platform-specific hacks needed to make it work reliably.

It is the low-level building block behind self-updating and self-uninstalling single-binary tools, and is used under the hood by higher-level crates like self_update.

What You Get

• self_replace(new_binary) to atomically replace the running executable with an updated build
• self_delete() to uninstall the running executable at runtime
• self_delete_outside_path() for controlling where the self-deletion helper operates
• Cross-platform handling that hides the Windows-specific locking workarounds behind one API

Common Use Cases

• Implementing a myapp update command that swaps in a freshly downloaded binary
• Adding a myapp uninstall command that removes the tool cleanly
• Serving as the low-level primitive for a higher-level self-update framework

Under The Hood

Architecture - The public API in src/lib.rs is a thin cross-platform facade over two cfg-selected modules: unix.rs, where replacement is essentially a rename/overwrite of the executable path, and windows.rs, which works around the OS holding an exclusive handle on the running image. The Windows path stages a temporary copy, uses Win32 file-system and shell APIs to move the live binary aside and swap in the replacement, and arranges deferred cleanup so the running process can delete or replace its own on-disk file. tempfile provides the staging area.

Tech Stack - Pure Rust, edition 2018, MSRV 1.63. Dependencies are minimal: tempfile on all platforms, plus fastrand and a broad set of windows-sys Win32 feature modules (FileSystem, Environment, LibraryLoader, Threading, Shell, Security) on Windows only. It shells nothing out — the Windows dance is done through direct Win32 syscalls.

Code Quality - The crate keeps a very small, auditable surface (roughly 31 KB of Rust) with the risky platform logic quarantined in the Windows module. It ships runnable examples and integration test helpers (batch/shell/Makefile scripts drive real self-replacement scenarios), and with 822 stars it is widely relied upon and well exercised in production single-binary tools.

API Design - The API is intentionally tiny and hard to misuse: two top-level free functions cover the whole use case, mirroring std::fs ergonomics and returning io::Result. Callers get cross-platform correctness without learning any Windows-specific concepts, which is exactly why higher-level updater crates build on it.