What causes "cannot specify a git URL (`{url}`) with a version (`{v}`)." in rust-lang/cargo?

Remove the version suffix from the crate spec: `cargo add foo --git https://github.com/user/foo`

rust-lang/cargo · error · anyhow::Error

cannot specify a git URL

Error message

cannot specify a git URL (`{url}`) with a version (`{v}`).

What it means

Thrown by cargo add when a dependency is specified with both a version requirement (via crate@version syntax, e.g. foo@1.0) and a --git URL. These are mutually exclusive source specifications: a git source pins the version to what exists in the repository, so an explicit version requirement is meaningless.

Solutions

Remove the version suffix from the crate spec: `cargo add foo --git https://github.com/user/foo`
Or remove --git if you want a registry version: `cargo add foo@1.0`

Example fix

# before
cargo add foo@1.0 --git https://github.com/user/foo
# error: cannot specify a git URL with a version

# after — omit version when using --git
cargo add foo --git https://github.com/user/foo

Defensive patterns

Strategy: validation

Validate before calling

// Validate that version and git are not both specified
fn validate_add_args(crate_spec: &str, git_url: Option<&str>) -> Result<(), String> {
    let has_version = crate_spec.contains('@');
    if has_version && git_url.is_some() {
        return Err("cannot specify a git URL with a version; remove one".into());
    }
    Ok(())
}

Prevention

When using --git, omit the @version suffix from the crate name
When specifying a version, omit the --git flag
Review the cargo add command before running to ensure only one source is specified

When it happens

Trigger: Running `cargo add foo@1.0 --git https://github.com/user/foo` where both the @version suffix and --git flag are present.

Common situations: Copy-pasting a version from one command and a git URL from another. Forgetting to remove the version specifier when switching from registry to git source. Following outdated examples.

Related errors

AI-assisted analysis of rust-lang/cargo@98a09e7e7d (2026-08-11). Data as JSON: /api/errors/36dc5c8fedd937e5. Report an issue: GitHub.

Appendix: source

Thrown at src/ops/cargo_add/mod.rs:373

        .as_deref()
        .map(CrateSpec::resolve)
        .transpose()?;
    let mut selected_dep = if let Some(url) = &arg.git {
        let mut src = GitSource::new(url);
        if let Some(branch) = &arg.branch {
            src = src.set_branch(branch);
        }
        if let Some(tag) = &arg.tag {
            src = src.set_tag(tag);
        }
        if let Some(rev) = &arg.rev {
            src = src.set_rev(rev);
        }

        let selected = if let Some(crate_spec) = &crate_spec {
            if let Some(v) = crate_spec.version_req() {
                // crate specifier includes a version (e.g. `docopt@0.8`)
                anyhow::bail!("cannot specify a git URL (`{url}`) with a version (`{v}`).");
            }
            let dependency = crate_spec.to_dependency()?.set_source(src);
            let selected = select_package(&dependency, gctx, registry)?;
            if dependency.name != selected.name {
                gctx.shell().warn(format!(
                    "translating `{}` to `{}`",
                    dependency.name, selected.name,
                ))?;
            }
            selected
        } else {
            let source = crate::sources::GitSource::new(src.source_id()?, gctx)?;
            let packages = source.read_packages()?;
            let package = infer_package_for_git_source(packages, &src)?;
            Dependency::from(package.summary())
        };
        selected
    } else if let Some(raw_path) = &arg.path {

View on GitHub (pinned to 98a09e7e7d)