How to Use Badges and Shields in crates.io README

Cargo
2026-04-17T16:32:01+00:00
You can add badges to your `README.md` by embedding Markdown image links that point to the Shields.io service, using your crate's name and version as dynamic parameters.

You can add badges to your README.md by embedding Markdown image links that point to the Shields.io service, using your crate's name and version as dynamic parameters. These badges automatically update to reflect your current version, build status, or license without manual intervention.

For the most common use case (displaying the current version), use the following syntax in your README.md:

[![Crates.io](https://img.shields.io/crates/v/your-crate-name.svg)](https://crates.io/crates/your-crate-name)

Replace your-crate-name with the actual name of your crate as defined in Cargo.toml. When the page loads, Shields.io fetches the latest version from crates.io and renders the badge. You can also combine this with a build status badge if you use GitHub Actions:

[![Build Status](https://github.com/your-username/your-repo/actions/workflows/ci.yml/badge.svg)](https://github.com/your-username/your-repo/actions)

Place these lines at the very top of your README.md, typically right under the title and before the description. This ensures they are visible immediately to anyone browsing your crate on crates.io or GitHub.

If you want to customize the appearance, Shields.io supports various styles and colors. For example, to use a flat style with a specific color:

[![Version](https://img.shields.io/crates/v/your-crate-name?style=flat&color=blue)](https://crates.io/crates/your-crate-name)

Common parameters include style (options: flat, flat-square, plastic, for-the-badge, social) and color (any hex code or named color). You can also add a license badge directly:

[![License](https://img.shields.io/crates/l/your-crate-name)](https://github.com/your-username/your-repo/blob/main/LICENSE)

Ensure your Cargo.toml has the correct license field (e.g., license = "MIT" or license = "MIT OR Apache-2.0") so the license badge reflects the accurate information. These badges are static HTML images generated on the fly, so they do not require any Rust code changes or dependencies in your project; they are purely documentation enhancements.

If your crate is not yet published, the version badge will show "0.0.0" or fail to load until the first release is pushed to crates.io. Always verify the badge renders correctly in a local Markdown previewer or by checking the rendered view on GitHub before pushing to ensure the links and parameters are correct.