[Avg. reading time: 4 minutes]
Cargo dependency versions
Cargo follows Semantic Versioning: MAJOR.MINOR.PATCH.
- MAJOR changes can break your code
- MINOR adds features but stays compatible
- PATCH is bug fixes only
While specifying the dependency version, you can either specify the exact one or mention the bottom range number.
Here are some more examples of version requirements and the versions that would be allowed with them:
For stable crates (1.x and above)
• 1.2.3 means ≥ 1.2.3 and < 2.0.0
• 1.2 means ≥ 1.2.0 and < 2.0.0
• 1 means ≥ 1.0.0 and < 2.0.0
For pre-1.0 crates (0.x)
Cargo is stricter because breaking changes are expected.
• 0.2.3 means ≥ 0.2.3 and < 0.3.0
• 0.2 means ≥ 0.2.0 and < 0.3.0
• 0.0.3 means ≥ 0.0.3 and < 0.0.4
• 0.0 means ≥ 0.0.0 and < 0.1.0
• 0 means ≥ 0.0.0 and < 1.0.0
Rule of thumb
- For 0.x crates, MINOR is treated like MAJOR
- Expect breakage even on small bumps
Wildcards
- ‘*’ means anything, including breaking garbage
- 1.* means ≥ 1.0.0 and < 2.0.0
- 1.2.* means ≥ 1.2.0 and < 1.3.0
Note: Don’t use wildcards in Production.
Using git repositories
[dependencies]
regex = { git = "https://github.com/rust-lang/regex" }
- The risk of bypassing crates.io versioning.
- hard to reproduce as git versioning is not controlled by Cargo.
- Use it on (internal) projects where you have control.