rust-lang/cargo · error

invalid character `+` in package name: `+{toolchain}` Us

Error message

invalid character `+` in package name: `+{toolchain}`
    Use `cargo +{toolchain} install` if you meant to use the `{toolchain}` toolchain.

What it means

From install::exec (src/bin/cargo/commands/install.rs:153-159). For each crate argument, if the name begins with `+`, Cargo treats it as a misplaced toolchain override and bails, suggesting the correct `cargo +<toolchain> install` order. The `+` prefix is reserved by Cargo for toolchain selection, which must precede the subcommand.

Source

Thrown at src/bin/cargo/commands/install.rs:154

    for (crate_name, _) in krates.iter() {
        let package_name = PackageName::new(crate_name);
        if !crate_name.contains("@") && package_name.is_err() {
            for (idx, ch) in crate_name.char_indices() {
                if !(unicode_ident::is_xid_continue(ch) || ch == '-') {
                    let mut suggested_crate_name = crate_name.to_string();
                    suggested_crate_name.insert_str(idx, "@");
                    if let Ok((_, Some(_))) = parse_crate(&suggested_crate_name.as_str()) {
                        let err = package_name.unwrap_err();
                        return Err(
                            anyhow::format_err!("{err}\n\n\
                                help: if this is meant to be a package name followed by a version, insert an `@` like `{suggested_crate_name}`").into());
                    }
                }
            }
        }

        if let Some(toolchain) = crate_name.strip_prefix("+") {
            return Err(anyhow!(
                "invalid character `+` in package name: `+{toolchain}`
    Use `cargo +{toolchain} install` if you meant to use the `{toolchain}` toolchain."
            )
            .into());
        }

        if let Ok(url) = crate_name.into_url() {
            if matches!(url.scheme(), "http" | "https") {
                return Err(anyhow!(
                    "invalid package name: `{url}`
    Use `cargo install --git {url}` if you meant to install from a git repository."
                )
                .into());
            }
        }

        if crate_name != "."
            && let Err(e) = package_name

View on GitHub (pinned to 0e07a15537)

Solutions

1. Put the toolchain before the subcommand: `cargo +<toolchain> install <crate>`.
2. If `+name` was not meant as a toolchain, remove the `+`.
3. Check shell quoting for stray `+`.

Example fix

// before
cargo install +nightly ripgrep

// after
cargo +nightly install ripgrep

// Build an install command with the toolchain in the correct position
fn build_install_cmd(toolchain: Option<&str>, crate_name: &str) -> Vec<String> {
    let mut v: Vec<String> = vec!["cargo".into()];
    if let Some(tc) = toolchain.filter(|t| !t.is_empty()) {
        v.push(format!("+{tc}"));
    }
    v.push("install".into());
    assert!(!crate_name.starts_with('+'), "crate name must not start with +");
    v.push(crate_name.into());
    v
}

fn looks_like_toolchain_override(arg: &str) -> bool {
    arg.starts_with('+') && arg.len() > 1
}

When it happens

Trigger: Running `cargo install +nightly ripgrep` instead of `cargo +nightly install ripgrep`. A shell snippet concatenating `+toolchain` in the wrong position.

Common situations: Misordered toolchain override in scripts/docs; copy-paste from an example that had the wrong order.

Related errors

• invalid character `+` in dependency name: `+{toolchain}`
• missing crate name before '@'
• argument for --color must be auto, always, or never, but fou
• invalid package name: `{url}` Use `cargo install --git {
• crate name is empty

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