|new 0.7.29||Dec 5, 2023|
|0.7.0-alpha.4||May 20, 2023|
|0.7.0-alpha.3||Mar 3, 2023|
|0.1.0||Nov 29, 2018|
#26 in Rust patterns
2,427,413 downloads per month
Used in 8,587 crates (123 directly)
Want to help improve zerocopy? Fill out our user survey!
Fast, safe, compile error. Pick two.
Zerocopy makes zero-cost memory manipulation effortless. We write
so you don't have to.
Zerocopy provides four core marker traits, each of which can be derived
FromZeroesindicates that a sequence of zero bytes represents a valid instance of a type
FromBytesindicates that a type may safely be converted from an arbitrary byte sequence
AsBytesindicates that a type may safely be converted to a byte sequence
Unalignedindicates that a type's alignment requirement is 1
Types which implement a subset of these traits can then be converted to/from byte sequences with little to no runtime overhead.
Zerocopy also provides byte-order aware integer types that support these
conversions; see the
byteorder module. These types are especially useful
for network parsing.
no_std. When the
allocfeature is enabled, the
alloccrate is added as a dependency, and some allocation-related functionality is added.
byteorder(enabled by default) Adds the
byteordermodule and a dependency on the
byteordermodule provides byte order-aware equivalents of the multi-byte primitive numerical types. Unlike their primitive equivalents, the types in this module have no alignment requirement and support byte order conversions. This can be useful in handling file formats, network packet layouts, etc which don't provide alignment guarantees and which may use a byte order different from that of the execution platform.
deriveProvides derives for the core marker traits via the
zerocopy-derivecrate. These derives are re-exported from
zerocopy, so it is not necessary to depend on
However, you may experience better compile times if you instead directly depend on both
Cargo.toml, since doing so will allow Rust to compile these crates in parallel. To do so, do not enable the
derivefeature, and list both dependencies in your
Cargo.tomlwith the same leading non-zero version number; e.g:
[dependencies] zerocopy = "0.X" zerocopy-derive = "0.X"
simdfeature is enabled,
AsBytesimpls are emitted for all stable SIMD types which exist on the target platform. Note that the layout of SIMD types is not yet stabilized, so these impls may be removed in the future if layout changes make them invalid. For more information, see the Unsafe Code Guidelines Reference page on the layout of packed SIMD vectors.
simdfeature and adds support for SIMD types which are only available on nightly. Since these types are unstable, support for any type may be removed at any point in the future.
Zerocopy is expressly designed for use in security-critical contexts. We strive to ensure that that zerocopy code is sound under Rust's current memory model, and any future memory model. We ensure this by:
- ...not 'guessing' about Rust's semantics.
unsafecode with a precise rationale for its soundness that cites a relevant section of Rust's official documentation. When Rust's documented semantics are unclear, we work with the Rust Operational Semantics Team to clarify Rust's documentation.
- ...rigorously testing our implementation. We run tests using Miri, ensuring that zerocopy is sound across a wide array of supported target platforms of varying endianness and pointer width, and across both current and experimental memory models of Rust.
- ...formally proving the correctness of our implementation. We apply formal verification tools like Kani to prove zerocopy's correctness.
For more information, see our full soundness policy.
Relationship to Project Safe Transmute
Project Safe Transmute is an official initiative of the Rust Project to develop language-level support for safer transmutation. The Project consults with crates like zerocopy to identify aspects of safer transmutation that would benefit from compiler support, and has developed an experimental, compiler-supported analysis which determines whether, for a given type, any value of that type may be soundly transmuted into another type. Once this functionality is sufficiently mature, zerocopy intends to replace its internal transmutability analysis (implemented by our custom derives) with the compiler-supported one. This change will likely be an implementation detail that is invisible to zerocopy's users.
Project Safe Transmute will not replace the need for most of zerocopy's
higher-level abstractions. The experimental compiler analysis is a tool for
checking the soundness of
unsafe code, not a tool to avoid writing
unsafe code altogether. For the foreseeable future, crates like zerocopy
will still be required in order to provide higher-level abstractions on top
of the building block provided by Project Safe Transmute.
See our MSRV policy.
Disclaimer: Zerocopy is not an officially supported Google product.