smol: the async runtime that is eleven crates wearing one name
A small and fast async runtime for Rust
At a glance
- What is it?
- smol-rs/smol is not a scheduler you configure but a facade over smaller async crates, so the interesting decisions live in the re-export list, the target gates, the 2.0.2 version pinned since September 2024, and the self-signed certificate the TLS examples load.
- Who is it for?
- smol fits codebases that want async primitives and a short dependency list rather than a runtime with batteries included, and the bill arrives at the edges: version 2.0.2 sits almost two years behind master, the TLS examples load an untrusted certificate, and tokio interoperability depends on a separate adapter crate.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 27 days ago.
- What is it written in?
- Mainly Rust, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.
Star history
- smol-rs/smol5,125 ★ · +54
| Repository | 2026-09-23 | 2026-11-21 |
|---|---|---|
| smol-rs/smol | 5.1k | 5.1k |
54 Stars in the last 59 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The crate ships no runtime of its own, only eleven re-exports
smol-rs/smol has no scheduler, no poller and no waker of its own. The opening line of the README puts it plainly: this crate simply re-exports other smaller async crates (see the source). What you compile is a facade over sibling projects, and the manifest specifies compatible version requirements for its direct dependencies:
[dependencies]
async-channel = "2.0.0"
async-executor = "1.5.0"
async-fs = "2.0.0"
async-io = "2.1.0"
async-lock = "3.0.0"
async-net = "2.0.0"
blocking = "1.3.0"
futures-lite = "2.0.0"
[target.'cfg(not(target_os = "espidf"))'.dependencies]
async-process = "2.0.0"The subcrate list goes wider than that dependency block. polling is described as a portable interface to epoll, kqueue, event ports and wepoll. async-task is the task abstraction for building executors, async-executor holds the composable executors, async-channel covers multi-producer multi-consumer channels, async-fs the async filesystem primitives, async-lock the barrier, mutex, reader-writer lock and semaphore, async-net the TCP, UDP and Unix sockets, blocking a thread pool for blocking I/O, and futures-lite a lighter fork of futures. Transitive dependencies also appear in Cargo.lock; preserve and review the lockfile to make application builds reproducible.
block_on drives one future, and Unblock handles the parts that block
The only execution entry point the README demonstrates is smol::block_on, which drives a single future to completion on the calling thread. This is the entire first program: open a TCP stream, write a hand built HTTP/1.1 request, and copy the response into standard output.
use smol::{io, net, prelude::*, Unblock};
fn main() -> io::Result<()> {
smol::block_on(async {
let mut stream = net::TcpStream::connect("example.com:80").await?;
let req = b"GET / HTTP/1.1\r\nHost: example.com\r\nConnection: close\r\n\r\n";
stream.write_all(req).await?;
let mut stdout = Unblock::new(std::io::stdout());
io::copy(stream, &mut stdout).await?;
Ok(())
})
}Two choices carry the design. The request is a byte string literal rather than a typed client, so nothing here depends on a protocol library. Standard output is wrapped in Unblock::new(std::io::stdout()) before io::copy touches it, because printing is blocking work and the blocking crate exists to move such work off the async path. The imports arrive through smol's prelude glob, and the README never enumerates which traits that prelude exports, so a reader guessing at method availability is guessing. If you would rather have async main plus a multi-threaded Executor without writing this scaffolding, the project points at a separate crate, smol-macros, for a no proc-macro, fast compiling setup.
The examples directory is the feature list, and it is a flat list of files
The examples directory is the closest thing smol has to documentation of scope, and it reads as a catalogue of protocols and platforms rather than a tutorial. Twenty-three files sit there and the names do the explaining. There are pairs for async-h1-client.rs and async-h1-server.rs, chat-client.rs and chat-server.rs, simple-client.rs and simple-server.rs, tcp-client.rs and tcp-server.rs for raw sockets, tls-client.rs and tls-server.rs for the secure variants, hyper-client.rs and hyper-server.rs for the hyper path, and websocket-client.rs and websocket-server.rs. Standalone ones include get-request.rs, web-crawler.rs and ctrl-c.rs. Four names carry an operating system: linux-inotify.rs, linux-timerfd.rs, windows-uds.rs and unix-signal.rs. Two entries are not Rust at all, certificate.pem and identity.pfx, the test key material the TLS examples load. What is absent matters as much as what is there. No routing layer, no middleware, no connection pool, no retry policy, no graceful shutdown helper, no configuration file format, and no benchmark harness. Every example is one self contained file you can read end to end, which is exactly why the primitives stop where they stop.
Target gates decide which files compile on your machine
Build time gates narrow that catalogue further. async-process is not an ordinary dependency: it sits under the cfg(not(target_os = "espidf")) target table, so a build for an ESP-IDF target gets no async interface for working with processes at all, and code reaching for smol::process there fails to compile. The dev-dependencies are gated even harder. inotify 0.11 with default-features disabled, rustix 1.0 and timerfd 1 exist only under cfg(target_os = "linux"), while uds_windows 1 exists only under cfg(windows). Read that as a statement about the machines the examples are maintained on, not as a portability promise. A Linux checkout builds linux-inotify.rs and linux-timerfd.rs; a Windows checkout builds windows-uds.rs; neither builds the other's file, and both will fail on an example you found by browsing the directory. The repository ships a .github/ directory and a workflow badge link, but no written platform matrix and no stated list of targets under test, so nobody has committed to your target working.
Version 2.0.2 predates the last push by about two years
The version field in Cargo.toml still reads 2.0.2, and the comment above it spells out the release ritual: update CHANGELOG.md, then create a v2.x.y git tag. The three most recent releases follow that habit. v2.0.0 landed on 2023-12-31, v2.0.1 on 2024-08-14, and v2.0.2 on 2024-09-07. Three releases, then no version bump, even though the default branch is master and its last push is dated 2026-10-26. The gap between the published crate and the current tip of master is close to two years. For a reader this cuts two ways. Add smol 2.0.2 as a dependency and Cargo hands you code from September 2024 no matter what has landed on master since. Work from a git checkout of master instead and you compile something ahead of the published crate, so your build can differ from what every other smol user gets. A project with a changelog, a tag convention and a version field that maintainers must keep in step treats the release number as the unit of trust, and that number has not moved since 2024.
The MSRV of 1.85 is pinned to Debian Stable, not to a Rust release
The Minimum Supported Rust Version is 1.85, stated twice: once in the prose policy and once as rust-version = "1.85" in the manifest, where an inline comment tells the maintainer to sync it with the MSRV Policy section. What makes the number unusual is the ceiling behind it. As a tentative policy, the MSRV will not advance past the current Rust version provided by Debian Stable, and at the time of writing that version is also 1.85. The floor can still move, in the event of a major ecosystem shift or a security vulnerability. edition = "2021" confirms the language level. Two practical consequences follow. Any toolchain older than 1.85 is refused by Cargo before compilation starts, so a CI image pinned to an older rustc fails outright instead of warning you. And because the ceiling is a distribution's compiler rather than a dated upstream release, the floor can rise without a matching Rust release announcement, leaving distributors and users to discover the change by hitting an error message. The README names no retirement date for 1.85 and no policy for how far ahead of Debian Stable it may drift.
The bundled certificate makes every TLS example fail verification
The TLS examples ship with a self-signed test certificate. The repository contains a self-signed certificate usable for testing, and the README says outright that it should not be used for real world scenarios; browsers and tools like curl show it as insecure. The escape hatch is accepting the browser security prompt, or bypassing the warning from a terminal with curl -k. The two files that carry it are examples/certificate.pem and examples/identity.pfx, the second produced by converting the generated key and certificate into a PKCS#12 bundle. The generation recipe is part of the README:
minica --domains localhost -ip-addresses 127.0.0.1 -ca-cert certificate.pem
openssl pkcs12 -export -out identity.pfx -inkey localhost/key.pem -in localhost/cert.pemmkcert is named as another useful tool for making certificates. For a reader the trap is plain once stated. Copy tls-client.rs or tls-server.rs into a project that faces real users and you have shipped a private key and a certificate no client trusts, with curl -k or a clicked warning standing between your service and a working handshake. Nothing in the README covers rotation, revocation, file permissions on key material, or any provisioning path for a certificate a client will accept.
tokio types cross the boundary only through async-compat
Rust has more than one async ecosystem, and smol's answer to the others is a wrapper crate rather than internal support. To use tokio-based libraries with smol, you apply the async-compat adapter to futures and I/O types. That single sentence is the whole documented path for reuse. The manifest shows the separation clearly: tokio appears only in dev-dependencies, as version 1 with default-features disabled and the single feature rt-multi-thread enabled, sitting next to futures = "0.3" and next to futures-lite, the lighter fork that smol actually ships. In other words tokio is present for the test suite, not for your application. If you adopt smol, every tokio typed dependency in your graph needs the adapter applied at each boundary where its futures or I/O types cross. The public surface stops at primitives: channels, executors, filesystem, timers, locks, networking, processes, tasks and a blocking thread pool. Everything above that line is a different crate.
Editorial conclusion
smol fits codebases that want async primitives and a short dependency list rather than a runtime with batteries included, and the bill arrives at the edges: version 2.0.2 sits almost two years behind master, the TLS examples load an untrusted certificate, and tokio interoperability depends on a separate adapter crate. Before committing, diff CHANGELOG.md on master against the published tag, build the examples your target needs, and reread the MSRV policy against your pinned toolchain.
Frequently asked questions
What does the smol crate actually contain?
A facade. The README states that the crate simply re-exports other smaller async crates, and Cargo.toml lists eight direct dependencies plus async-process behind a target gate that excludes espidf. Channels, locks, filesystem, timers and networking all live in those sibling crates.
How do I run my first async program with smol?
Wrap the future in smol::block_on, as the GET request example does, and wrap standard output in Unblock::new(std::io::stdout()) before copying into it, since printing is blocking work. For async main and a multi-threaded Executor, the project points at the separate smol-macros crate.
Can smol run tokio-based libraries?
Only through the async-compat adapter, which you apply to futures and I/O types. tokio itself is a dev-dependency with default-features = false and the rt-multi-thread feature, so it is exercised by the test suite rather than exposed by the crate.
Are the certificates in the smol examples safe to use in production?
No. The repository contains a self-signed certificate usable for testing, the README says it should not be used for real world scenarios, and browsers plus curl report it as insecure until you accept the prompt or pass curl -k.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/smol-rs-smol)Star history chart for your README
[](https://hysenlabs.com/projects/smol-rs-smol)Was this useful?