In a Cargo.toml, what does `json = { package = "serde_json", version = "1" }` change, and when is renaming a dependency worth doing?
answer
- the key is the name in code
- the package key names the real crate
- two majors side by side
- feature names follow the key
basics
~20 sThe package key names the real crate and the table key becomes the name code uses: this line depends on serde_json but code writes json::from_str. Renaming lets one package use two versions or two same-named crates side by side.
solid answer
~40 sNormally a dependency's key in `Cargo.toml` is both the package to fetch and the crate name in code. With `package = "serde_json"`, Cargo fetches `serde_json` but passes it to rustc under the key's name, so code says `json::Value`, and `serde_json::` no longer resolves (E0433). `package` defaults to the key. Renaming earns its place in three cases the Cargo book lists: avoiding a `use foo as bar` everywhere, depending on **two versions** of one crate, for example keeping 1.x under `wire-format-v1` while migrating to 2.x, and taking two crates with the **same name** from different sources, such as crates.io and a git fork or another registry. If the renamed dependency is optional, its implicit feature takes the key's name (`json`), not the package's. `cargo add serde_json --rename json` writes the line for you.
code
toml · 3 lines[dependencies]
wire-format = { path = "crates/wire-format", version = "2" }
wire-format-v1 = { path = "vendor-old/wire-format", version = "1", package = "wire-format" }go deeper
Recall that the key in Cargo.toml is the name you use in code and that package names the crate actually fetched.
Explain the three uses the Cargo book lists, and that cargo tree, Cargo.lock and features each show either the real name or the key.
Show how a renamed second major lets a migration proceed module by module, and why its types never interoperate with the new major's.
Treat a renamed duplicate as migration debt with an owner and an end date, since every extra copy costs compile time and binary size.
## The key and the package are normally the same In a `[dependencies]` table, the **key** on the left (`serde_json = "1"`) does two jobs: it names the **package** Cargo fetches and it names the **crate** your code refers to. The `package` key splits those jobs apart: ```toml [dependencies] json = { package = "serde_json", version = "1" } ``` Cargo resolves and builds the `serde_json` package exactly as before, but hands it to the compiler under the name `json`. When `package` is absent, the Cargo book says it "defaults to the name of the dependency being requested", which is why ordinary lines never need it. ## What changes for code and tooling - **Code** uses the key: `json::from_str(...)` and `json::Value`. Writing `serde_json::from_str` now fails with rustc's `E0433` ("use of unresolved module or unlinked crate"), because no crate of that name is passed to rustc. - **A hyphenated key** becomes an underscored crate name, as any dependency name does: `wire-format-v1` is written `wire_format_v1` in code. - **Cargo's own output** keeps the real package: `cargo tree` lists `serde_json v1.0.154`, and `Cargo.lock` has a `serde_json` entry. - **Features** follow the key. For `json = { package = "serde_json", version = "1", optional = true }`, the package gains a `json` feature, and `--features serde_json` fails with "does not contain this feature". The Cargo book's example makes the same point for a feature that enables a dependency's feature: write `bar/log-debug`, not `foo/log-debug`; how features are designed is a separate lesson. ## When renaming is worth it The Cargo book gives three reasons, and each fits a real situation: 1. **A shorter or clearer name.** Instead of `use serde_json as json;` at the top of every module, rename once in the manifest. This is the weakest reason: it surprises readers who search the code for the crate's real name, so keeping the published name is usually clearer unless it collides with something. 2. **Two versions of one crate.** During a migration from a 1.x to a 2.x API, a service can depend on both, keeping the old one under a new key. Cargo builds them as distinct crates, so their types are not interchangeable; how Cargo treats two majors elsewhere in the graph belongs to the resolver. 3. **Same name, different sources.** A crates.io release and a fork from git or another registry can share a package name. The book's example depends on three packages all named `foo`: one from crates.io as `foo`, one from git as `bar`, and one from a registry called `custom` as `baz`. Without the `package` key the three lines would all need the key `foo`, and one table cannot hold the same key twice; with it, each gets its own key and its own crate name. In every case, the renamed line is still a complete dependency specification: `version`, `git`, `path`, `registry`, `optional`, `features` and `default-features` all work beside `package` exactly as they would on an unrenamed line. ## Doing it safely Renaming is cheap to add and easy to forget, so a few habits keep it from confusing a team: - Name the old version explicitly, for example `wire-format-v1`, so its temporary status is obvious and `cargo tree` still shows both under the real package name. - Remove the second version when the migration ends; a renamed duplicate costs compile time and binary size for as long as it stays. - Mention the real package name in a comment beside an unusual key, so someone searching the code for `serde_json` still finds where it comes from. - Prefer `cargo add serde_json --rename json` to hand edits; in the run behind this answer it wrote `json = { version = "1.0.154", package = "serde_json" }`. | Want | Manifest line | Name in code | |---|---|---| | ordinary dependency | `serde_json = "1"` | `serde_json` | | shorter name | `json = { package = "serde_json", version = "1" }` | `json` | | old major beside new | `wire-format-v1 = { package = "wire-format", version = "1" }` | `wire_format_v1` | | fork from git | `foo-fork = { package = "foo", git = "..." }` | `foo_fork` | Renaming changes only the name your package sees. The version requirement, source keys and features in the same line keep their usual meaning, and the dependency's own name in its manifest is untouched.
- With `json = { package = "serde_json", version = "1", optional = true }`, what does `cargo build --features serde_json` do?It fails: Cargo reports that the package "does not contain this feature: serde_json". An optional dependency's implicit feature takes the dependency's key, not the package name, so the feature is `json` and `--features json` builds.
- Can a renamed second major of a crate accept values created by the first one?No. Cargo compiles the two versions as separate crates, so a `wire_format_v1::Record` and a `wire_format::Record` are different types even if their definitions match. Code converting between them has to go through something both understand, such as the encoded bytes or a hand-written conversion.
- The key is just a label; code still imports the crate by its package name.
- Renaming a dependency also renames the package in Cargo.lock.
- Cargo forbids depending on two versions of the same package.
- A renamed optional dependency's feature keeps the package's name.
- The package key changes which version Cargo resolves.