rust-smallvec: stack storage for short Rust vectors

Why rust-smallvec targets short Rust collections

rust-smallvec addresses Rust programs that repeatedly store only a few elements but still want vector-style operations. Its package description states the specific optimization: "store up to a small number of items on the stack." The intended audience is Rust developers working with bounded, short-lived collections where avoiding heap allocation may matter. The package is categorized as a data structure and carries `no_std` as a keyword, although the manifest also exposes optional features that depend on `std`.

This is a specialization of the vector abstraction, not a general database, arena, or fixed-capacity container. The repository description does not document a particular inline capacity or show how that capacity is selected. It also does not claim that every vector should use inline storage. The useful case is narrower: a collection commonly remains small enough for its contents to fit within the crate's inline representation.

The distinction matters because ordinary vector growth has allocation and reallocation costs, while inline storage introduces its own size and implementation choices. The README and package manifest do not provide comparative measurements, so claims about a particular speed, memory, or latency improvement cannot be confirmed from the repository documentation. Engineers should base adoption on element sizes, expected lengths, and call patterns rather than on an assumed universal improvement.

How inline storage changes vector use

The package description gives the central mechanism but does not document the internal type representation, inline element count, spill threshold, or transition from inline storage to heap storage. The architecture visible from the repository is therefore limited but clear: `src/` contains the implementation, `tests/` contains tests, and `fuzz/` contains fuzzing assets. `benches/` contains benchmark-related files, while `Cargo.toml` defines the package, features, dependencies, and benchmark profiles.

The intended data flow is small collection creation, inline storage for elements that fit within the small representation, and heap storage when the collection outgrows that representation. The documentation does not state whether growth is geometric, whether spare capacity is retained inline, or whether spilling can later return to inline storage. It also does not document whether the public type behaves identically to `Vec` for every operation. An application should therefore treat SmallVec as a collection with an inline-first design, not assume that its entire API surface is identical to the standard vector.

The repository includes a `callgrind` profile that retains symbols and debug information for benchmark event attribution. That is evidence of benchmark tooling, not evidence of a measured result. No benchmark values are reported in the README or package manifest, so the implementation should be evaluated against the application's actual element types and length distribution.

The v1 and v2 branches require separate decisions

The default `v2` branch contains code for SmallVec v2, which the README explicitly describes as pre-release. Its manifest declares version `2.0.0-beta.2`, edition `2024`, and `rust-version = "1.86"`. The listed `v2.0.0-beta.2` release on 2026-10-02 is therefore not the same maturity boundary as the stable `v1.16.3` release listed on 2026-10-06.

The README directs bug fixes for SmallVec v1 to the `v1` branch and says new feature development should go on the `v2` branch. It also directs readers to the project wiki for v2 status and management before making a contribution. That split creates an important deployment decision: a project seeking stable 1.x behavior should inspect the `v1` branch, while a project evaluating the new API should accept beta status and verify compatibility against its own compiler and dependencies.

The README does not document migration from v1 to v2, API differences, rollback procedures, or a compatibility guarantee. It also says that AI contributions are not allowed in any Servo repository and points contributors to Servo's AI contributions policy. The README names five people as v2 core contributors, but that contributor list does not change the repository's pre-release status.

Cargo features change the available build surface

The package manifest makes `smallvec` configurable through Cargo features rather than presenting one fixed build. The available switches are `allocator-api`, `allocator-api2`, `internals`, `proptest`, `rayon`, `serde`, `specialization`, `std`, and `zeroize`. Some features introduce dependencies or additional runtime requirements. `proptest` enables `std` and pulls in `proptest`, `rayon` enables `std` and pulls in `rayon`, and `zeroize` pulls in `zeroize`.

The manifest also lists optional integration dependencies including `allocator-api2`, `arbitrary`, `borsh`, `bytes`, `defmt`, `encase`, and `malloc_size_of`, although the dependency section is truncated before all optional entries can be confirmed. The repository layout adds `tests/`, `fuzz/`, and `benches/` for development work, while the package manifest excludes those directories from the published package. This makes the crate metadata broader than the files shipped in the package.

The README does not contain a feature matrix explaining which SmallVec APIs each switch changes. Feature selection should therefore be treated as an API verification task in the selected branch. A consumer who only needs the basic inline collection should first inspect default-feature behavior, then enable a named integration only when its dependency and environment requirements are understood. Features such as `rayon` and `proptest` also change the environment because they require `std`.

Installation and first use are not documented here

The README is a contribution notice rather than a user installation guide. It does not provide a `cargo add smallvec` command, a Cargo dependency snippet, or a first-program example. The project therefore does not document enough to reproduce a first use without inventing package configuration or API calls.

What can be confirmed is the package identity from `Cargo.toml`: the Cargo package is named `smallvec`, the default branch manifest reports version `2.0.0-beta.2`, and the repository metadata points to `https://github.com/servo/rust-smallvec`. Consumers looking for stable 1.x code are directed to the `v1` branch. The README does not state the exact dependency declaration for either line, so no installation block is included.

This lack of user-facing setup material is relevant for evaluation. An engineer can inspect `Cargo.toml` and the selected source branch, but must confirm the dependency version, default features, Rust toolchain, and public API before adding the crate to an application. The available repository layout also shows that `tests/`, `fuzz/`, and `benches/` are development areas rather than documented examples for a first use.

Upgrade cost, releases, and maintenance signals

The repository was not archived, and its last push was on 2026-10-16. That is recent repository activity based on the repository listing. Recent releases include `v1.16.3` on 2026-10-06, `v2.0.0-beta.2` on 2026-10-02, and `v1.16.2` on 2026-09-22. The sequence shows parallel work across stable 1.x releases and the v2 pre-release line, but it does not say when v2 will become stable.

Upgrade cost is most apparent in the branch policy. Applications using v1 should expect bug fixes to land on `v1`, while new work remains on `v2`. Because the README does not provide migration instructions or an API comparison, moving an established application to v2 would require source-level review. The stricter v2 toolchain requirement also matters: its manifest requires Rust 1.86 and edition 2024.

The repository contains a dedicated `Cargo.lock`, source under `src/`, tests under `tests/`, fuzz inputs and targets under `fuzz/`, and benchmarks under `benches/`. The manifest includes a `callgrind` profile with symbols and debug information retained for line-level event attribution. That setup documents benchmark intent, but it does not establish performance results.

Where SmallVec is the wrong choice

rust-smallvec is the wrong fit when collections are expected to become large, when inline storage would make every value larger than necessary, or when the application specifically needs the standard library's established `Vec` behavior. The package is an optimization for small collections, but the available documentation does not define the threshold at which heap storage takes over.

A real alternative is Rust's standard `Vec`, which stores vector elements in heap-allocated storage and is the baseline against which a small-vector abstraction should be evaluated. The practical difference is storage placement: rust-smallvec is designed to retain a small number of items inline, while `Vec` focuses on heap-backed vector storage. The repository documentation does not include an API-by-API comparison, benchmark results, or a statement that SmallVec preserves every `Vec` convenience API.

Another suitable decision is to keep a fixed-capacity inline array when the maximum length is known and operations can be expressed over a fixed size. The project description does not claim support for that replacement, so it is mentioned only as a design boundary. SmallVec should be chosen after checking element alignment, collection length, feature requirements, and branch maturity, not solely because its name suggests a faster vector.

The package is licensed under `MIT OR Apache-2.0`, with `LICENSE-APACHE` and `LICENSE-MIT` in the repository. That declaration identifies the offered licensing options, but it does not provide legal interpretation or a recommendation about which option a particular organization should select.

Editorial conclusion

Adopt the stable 1.x line for production collection work when small inline vectors fit the design. Do not treat the default v2 branch as a finished stable release. Before adoption, verify the exact 1.x API and feature set on the v1 branch, confirm that heap growth for larger collections is acceptable, and check whether your licenses and Rust toolchain satisfy `MIT OR Apache-2.0` and `rust-version = "1.86"` respectively.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. servo/rust-smallvec on GitHub