How to force cargo to use an internal server? (registry)

help
1

Question:

How can I force cargo to NOT use "https://cargo.io" - and instead use my specified URL?

Why?
I am working in an "closed" or "air gapped environment" -I have no internet connection.
I am setting up my own internal "crates.io" mirror.

Step 1:
Any time cargo goes to the web, I need it to use MY URL not https://crates.io
This does not seem to work, and I need to understand why so I can fix it.

I am using: cargo 1.88.0 (873a06493 2025-05-10)

Documentation I am following is this:

 https://doc.rust-lang.org/cargo/reference/config.html

This states that I can create two entries in ${CARGO_HOME}/config.toml
that should be sufficient to make cargo use my server instead, below is the output of:

bash$ cat $CARGO_HOME/config.toml

Output:

[registry]
default="local-registry"

[registries]
local-registry={ index="http://localhost:8080" }

It is my understanding that this should override default: 'https://crates.io" with my replacement server URL and have cargo use my-registry for all things.

However.. cargo ignores this. Thus I am stuck at square 1.

cargo download -v ahash

Note the: -v option which means verbose... What I see in the debug output is this:

D2025-08-11T04:40:28.0104Z main#160] Fetching latest matching version of crate `ahash=*` from https://crates.io/api/v1/crates/ahash/versions

Which tells me that Cargo is NOT honoring the default setting and not going to my server.

How do I make cargo use MY URL instead?

2

Important Notes

  • The registry index must be a Git repository in the format Cargo expects.
  • If you're replacing crates.io entirely, ensure your registry mirrors all required dependencies.
  • Some registries (like private ones) may require authentication. You can set credentials in ~/.cargo/credentials.toml:
    [registries.your-registry-name]
token = "your-auth-token"

Just for references !

3

the problem is this information like you describe is so dam scattered that setting up a mirror is painfully complex and non trivial

4

Custom registries are a wrong feature for this. They will always be interpreted as something separate and incompatible with crates.io.

Cargo has source replacement feature dedicated to replacing crates.io with other URLs or data sources.

There's also --offline flag you can use if you copy Cargo caches manually.

5

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.