socket2: the Rust crate for socket options the standard library leaves out

A thin layer that stops where the standard library stops

socket2 is described as a crate that provides utilities for creating and using sockets, with the goal of creating and using a socket using advanced configuration options, those that are not available in the types in the standard library, without using any unsafe code.

That framing sets the scope precisely. This is not a networking framework, and it is not a reimplementation of the standard library's socket types. It is the missing configuration surface. The repository description calls it "Advanced configuration options for sockets", and the Cargo.toml keywords are io, socket and network, with the api-bindings and network-programming categories.

The audience is Rust developers writing systems or network code who hit a wall with the standard library types, usually around socket options that the library does not expose, and who want to set them without writing their own unsafe block and a libc binding. The crate is also used as a dependency by other projects, and the API documentation lives on docs.rs, which is the homepage recorded for the repository.

The crate description in the manifest is blunt about its intended use: utilities for handling networking sockets with a maximal amount of configuration possible intended.

The README tells you who this crate is not for

The documentation contains the most direct advice in the whole repository, and it comes early. It says that if you do not know how to create a socket using libc or system calls, then this crate is not for you. That is not a throwaway remark about difficulty. It is a statement about the responsibility the crate leaves with the caller.

The reason is visible in how the API is designed. The crate provides, as the README puts it, as direct as possible access to the system's functionality for sockets, which means little effort to provide cross-platform utilities. Most, if not all, functions directly relate to the equivalent system call with no error handling applied, so no handling errors such as EINTR. The README is explicit that using the crate can be a little wordy as a result, but that it should give you maximal flexibility over configuration of sockets.

So the trade is clean and you should accept it knowingly. In exchange for thin wrappers that stay close to the system call, you take on the error handling that the standard library would have done for you. A wrapped system call that returns EINTR, or any other errno condition, surfaces as a raw result for you to interpret. If you are comfortable reading errno values, this is a good crate. If you want a socket type that recovers from interrupts on its own, it is the wrong one.

The all feature flag is where cross-platform promises stop

The Cargo.toml defines a single feature, all, with the comment that it enables all API, even ones not available on all OSs. The feature list is short, which makes the flag easy to reason about, but its effect is the important detail: enabling it exposes calls that exist on some platforms and not others.

The README organises operating systems into two tiers, and the distinction maps directly onto how much you can trust a given target. Tier 1 systems are tested with each commit in the CI and must always pass the tests, and all functions and types must work on them, excluding the ones behind the all feature. Those systems are Linux, macOS and Windows.

Tier 2 systems are currently built in the CI but not tested, and the README warns that not all functions and types may work on them, even ones not behind the all feature flag. The Tier 2 list is Android, FreeBSD, Fuchsia, iOS, illumos, NetBSD, Redox, Solaris and OpenHarmony.

The practical reading is that a CI green build on a Tier 2 platform tells you the code compiles there, not that the behaviour matches Linux. If you ship on Android or one of the BSDs, that is the difference between a portability claim and a portability assumption, and it is worth testing on the actual device rather than the build matrix.

Three branches, MSRV 1.70, and platform specific dependencies

The repository maintains parallel release lines and names them explicitly. Version 0.6 is developed in the master branch, 0.5 is developed in the v0.5.x branch, and 0.4 is developed in the v0.4.x branch. A dependency that cannot move to the current line can therefore still be pointed at a maintained branch, which is the practical reason to keep old lines alive at all.

The manifest records version 0.6.5 with edition 2021 and a rust-version of 1.70, matching the README statement that socket2 uses 1.70.0 as its minimum supported Rust version. That floor is old enough to be unconstraining for most projects, but it does mean the crate can be pulled into codebases pinned to older toolchains without a dependency bump.

Dependencies are deliberately narrow and platform scoped. On Unix and wasi targets the manifest pulls in libc at 0.2.190. On Windows it pulls windows-sys with a version range of at least 0.60 and below 0.62, and the enabled Windows features are Win32_Foundation, Win32_Networking_WinSock, Win32_System_IO, Win32_System_Threading and Win32_System_WindowsProgramming. Only the Wsock and threading parts are strictly needed for sockets, so the wider feature set suggests the crate is used by components that also need the other pieces, and the windows-sys upper bound means a Windows upgrade can eventually force a version bump.

The Makefile runs the whole feature matrix, not just the defaults

The repository root carries a Makefile whose targets mirror the CI and the docs.rs configuration. The default test target is a single line:

cargo test --all-features

The broader target, test_all, first runs check_all_targets and then exercises the feature powerset in both debug and release:

cargo hack test --feature-powerset
cargo hack test --feature-powerset --release

cargo hack is what makes the feature matrix tractable. Because the crate has only one feature, the powerset is small, but the pattern matters: a new feature can be switched on and off against every target without hand written combinations. The per-target check expands to a longer invocation:

cargo hack check --feature-powerset --all-targets --examples --bins --tests --target $@

The list of targets it loops over is set in the Makefile itself and includes aarch64-apple-ios, x86_64-pc-windows-msvc, x86_64-unknown-redox, x86_64-unknown-musl and others, and a separate target installs the required Rust targets with rustup target add $(TARGETS). The docs.rs metadata in the manifest builds with all-features = true and lists the same family of targets, so the published documentation on docs.rs reflects the widest configuration.

There is also a dev target that watches the source tree:

find src/ tests/ Makefile Cargo.toml | entr -d -c $(MAKE) test

That one line tells you where the code lives: src/ for the crate itself and tests/ for the test suite, with the manifest and Makefile watched alongside them.

Dual licensing, and GitHub release tags that stopped years ago

Two facts about the packaging deserve attention before you depend on the crate.

The first is the licence. The README states the project is licensed under either the Apache License, Version 2.0 or the MIT license, at your option, and the Cargo.toml license field reads MIT OR Apache-2.0. The repository listing records Apache-2.0, which is a narrower reading of the same arrangement. Either way the terms are permissive and the choice of which file you comply with is yours, though how a downstream project pairs the two with its own licence is a question for your own legal review rather than for this article.

The second is version history. The releases recorded for the repository are v0.2.0 from June 2017, v0.2.2 from August 2017 and v0.2.4 from October 2017. Meanwhile the manifest declares version 0.6.5. So the GitHub release list is not the version history of the current crate, and the CHANGELOG.md file at the repository root is where the recent story lives. If you upgrade a dependency by watching GitHub tags, you will see a decade-old picture of the project.

The code itself is current: the last push was on 2026-10-18, and the repository holds a .github/ directory, a CONTRIBUTING.md and a Makefile, so the project is being worked on even though the release tags are not.

Where the standard library is the better choice

socket2 is the wrong tool in a common case: any socket that needs no unusual configuration. The standard library types cover ordinary TCP connections, listeners and UDP sockets, and using them means less code, no extra dependency and error handling you did not have to write yourself.

The difference in approach is not that socket2 does more work. It does less wrapping. The standard library decides for you which errors are retried and which are returned, and it exposes a fixed set of options. socket2 exposes more options and leaves the error handling entirely to the caller, which buys you flexibility and costs you verbosity.

Two further limits are worth weighing. The crate is not tested on Tier 2 platforms, so if your target is Android or one of the BSDs, the standard library path is the safer default for common cases and socket2 is the deliberate exception. And the all feature flag bypasses the guarantee that everything works everywhere, so enabling it in a shared dependency graph can move a failure into a platform that nobody tests.

In short, reach for socket2 when you know exactly which system call you need and the standard library will not give it to you, and stay with the standard library when you are choosing a socket type rather than fighting one.

Editorial conclusion

Adopt socket2 when you need a socket option that the standard library types do not expose, and you already understand what the underlying system call does, because the crate deliberately adds no error handling of its own and expects the caller to know the socket API. Do not adopt it for ordinary TCP work, where the standard library types are shorter and the difference in behaviour is invisible. Before you commit, confirm the tier of the platform you ship on, since Android, FreeBSD, Fuchsia, iOS, illumos, NetBSD, Redox, Solaris and OpenHarmony are built in CI but not tested, and check whether the options you need sit behind the all feature flag, which the README says is not guaranteed on every platform.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. rust-lang/socket2 on GitHub