rust-lang/cargo · error

cannot specify multiple crates with `--rename`

Error message

cannot specify multiple crates with `--rename`

What it means

From parse_dependencies (src/bin/cargo/commands/add.rs:359-361). After building the list of DepOp entries, if more than one crate is being added and --rename is set, Cargo bails because a single rename target cannot apply to multiple crates unambiguously.

Source

Thrown at src/bin/cargo/commands/add.rs:360

            crate_spec,
            rename: rename.map(String::from),
            features,
            default_features,
            optional,
            public,
            registry: registry.clone(),
            path: path.map(String::from),
            base: base.map(String::from),
            git: git.map(String::from),
            branch: branch.map(String::from),
            rev: rev.map(String::from),
            tag: tag.map(String::from),
        };
        deps.push(dep);
    }

    if deps.len() > 1 && rename.is_some() {
        anyhow::bail!("cannot specify multiple crates with `--rename`");
    }

    Ok(deps)
}

fn default_features(matches: &ArgMatches) -> Option<bool> {
    resolve_bool_arg(
        matches.flag("default-features"),
        matches.flag("no-default-features"),
    )
}

fn optional(matches: &ArgMatches) -> Option<bool> {
    resolve_bool_arg(matches.flag("optional"), matches.flag("no-optional"))
}

fn public(matches: &ArgMatches) -> Option<bool> {
    resolve_bool_arg(matches.flag("public"), matches.flag("no-public"))

View on GitHub (pinned to 0e07a15537)

Solutions

1. Add crates one at a time if you need --rename: `cargo add serde --rename my-serde` then `cargo add tokio`.
2. Drop --rename when adding multiple crates.
3. Edit Cargo.toml manually to set the package name + package key for renamed deps.

Example fix

// before
cargo add serde tokio --rename my-serde

// after
cargo add serde --rename my-serde && cargo add tokio

// Only allow --rename with a single crate
fn add_command_valid(crates: &[String], rename: Option<&str>) -> bool {
    rename.is_none() || crates.len() == 1
}

When it happens

Trigger: `cargo add serde tokio --rename my-serde` — renaming is only meaningful for a single dependency.

Common situations: Batch-adding crates and trying to rename at the same time; script that loops and forgets --rename is per-invocation.

Related errors

• invalid character `+` in dependency name: `+{toolchain}`
• feature `{feature}` must be qualified by the dependency it's
• feature `{feature}` is not allowed to use explicit `dep:` sy
• `{feature}` is unsupported when inferring the crate name, us
• multiple slashes in feature `{feature}` is not allowed

AI-assisted analysis of rust-lang/cargo@0e07a15537 (2026-08-06). Data as JSON: /data/errors/b40742b3dc426ad1.json. Report an issue: GitHub.