Cargo build stuck: "Blocking waiting for file lock" — how to fix

Introduction: when Rust compilation turns into a quest

You decided to build Parity (or any other complex Rust project) from source. The cargo build command is running, the terminal is silent, and after a minute you see a message familiar to many:

Blocking waiting for file lock on the registry index

The build hangs completely. Ctrl+C doesn't help, restarting the terminal doesn't either. Sound familiar? This problem is one of the most popular on Stack Overflow (thousands of views), and today we'll break it down to the smallest detail.

In this article, as your guide to the world of Rust, I will tell you:
\n- Why does this error occur?
\n- How to fix it in 30 seconds?
\n- How to prevent it from happening altogether?
\n- And we'll take a little look under the hood of Cargo.

Let's go! 🚀

Where does "Blocking waiting for file lock on the registry index" come from?

First, let's translate this error from Cargo language into human language:

"I, Cargo, want to download or update the package list from the registry, but I can't — the lock file is already held by another process. Waiting..."

In the Rust ecosystem, cargo uses file locks (.lock files) to prevent two processes from trying to write to the registry cache (~/.cargo/registry) at the same time. This protects against data corruption, but sometimes the lock "sticks".

Main causes of the hang

\n
• Abnormal termination of a previous build — you closed the terminal, the computer shut down, or cargo build crashed with an error, but the lock file remained.
\n
• Two instances of Cargo in the same project — started a build in two terminal windows simultaneously.
\n
• Building Parity from source — this project pulls in a huge number of dependencies (hundreds of crates), and Cargo can hang during the indexing phase, especially on weak machines or with a slow internet connection.
\n
• Permission issues — rare, but can happen when ~/.cargo belongs to another user.
\n
• File system without lock support — for example, some network shares or WSL without proper configuration.
\n

5 methods of solution (from quick to reliable)

🔧 Method 1: Kill the Cargo process (fastest)

If you are sure that no other build is running, simply terminate the process holding the lock.

Linux/macOS:

pkill cargo\n# or more forcefully:\nkillall -9 cargo

Windows (PowerShell):

Get-Process cargo | Stop-Process -Force

After that, run cargo build again. In 80% of cases, this is enough.

🔧 Method 2: Manually delete the lock file

If the first method didn't help, go to the registry directory and delete the lock file.

Path:

# Linux/macOS\nrm -f ~/.cargo/registry/.cache-lock\nrm -f ~/.cargo/registry/.package-cache\n\n# Windows (cmd)\ndel %USERPROFILE%\\.cargo\\registry\\.cache-lock\ndel %USERPROFILE%\\.cargo\\registry\\.package-cache

After this, Cargo will create a new lock file on the next run. Important: make sure no other Cargo processes are running, otherwise you risk damaging the cache.

🔧 Method 3: Cargo clean — the nuclear option

If nothing helps, clear everything that has accumulated. This will delete the target folder and reset the dependency cache for the current project. The next build will take longer, but it will be clean.

cargo clean

After that, try building the project again:

cargo build

This method is especially useful if you were building Parity or another project with a huge dependency tree.