Documentation Index
Fetch the complete documentation index at: https://mintlify.com/fussybeaver/bollard/llms.txt
Use this file to discover all available pages before exploring further.
The system API methods provide access to Docker daemon metadata, health checks, disk usage reporting, and the real-time event stream. All methods are available directly on the Docker struct with no additional imports beyond bollard::Docker.
Methods
version
pub async fn version(&self) -> Result<SystemVersion, Error>
SystemVersion
use bollard::Docker;
#[tokio::main]
async fn main() {
let docker = Docker::connect_with_socket_defaults().unwrap();
let version = docker.version().await.unwrap();
println!("Docker version: {:?}", version.version);
println!("API version: {:?}", version.api_version);
}
info
pub async fn info(&self) -> Result<SystemInfo, Error>
SystemInfo
use bollard::Docker;
#[tokio::main]
async fn main() {
let docker = Docker::connect_with_socket_defaults().unwrap();
let info = docker.info().await.unwrap();
println!("Containers running: {:?}", info.containers_running);
println!("Docker root dir: {:?}", info.docker_root_dir);
}
ping
pub async fn ping(&self) -> Result<String, Error>
GET /_ping). Returns the string "OK" when the daemon is reachable. Use this to verify connectivity before making other API calls.
Returns: String — always "OK" on success.
use bollard::Docker;
#[tokio::main]
async fn main() {
let docker = Docker::connect_with_socket_defaults().unwrap();
let response = docker.ping().await.unwrap();
assert_eq!(response, "OK");
println!("Daemon is reachable.");
}
pub async fn df(
&self,
options: Option<DataUsageOptions>,
) -> Result<SystemDataUsageResponse, Error>
None for default behaviour (all resource types).
Options: bollard::query_parameters::DataUsageOptions
Returns: SystemDataUsageResponse
use bollard::Docker;
use bollard::query_parameters::DataUsageOptions;
#[tokio::main]
async fn main() {
let docker = Docker::connect_with_socket_defaults().unwrap();
let usage = docker.df(None::<DataUsageOptions>).await.unwrap();
if let Some(images) = usage.images {
println!("Image count: {}", images.len());
}
if let Some(containers) = usage.containers {
println!("Container count: {}", containers.len());
}
}
events
pub fn events(
&self,
options: Option<EventsOptions>,
) -> impl Stream<Item = Result<EventMessage, Error>>
Stream yields one EventMessage per daemon event. The stream stays open until the connection is dropped or an error occurs.
Options: bollard::query_parameters::EventsOptions (built via EventsOptionsBuilder)
| Builder field | Type | Description |
|---|
since | &str | Show events since a timestamp or relative duration (e.g. "1h"). |
until | &str | Show events until a timestamp. |
filters | &HashMap<&str, Vec<&str>> | Filter by type, event, image, container, label, etc. |
impl Stream<Item = Result<EventMessage, Error>>
events returns a lazy Stream, not a Future. You must iterate it using StreamExt or TryStreamExt. The stream does not terminate on its own — wrap it in tokio::time::timeout or select it against a cancellation signal for bounded execution.
use bollard::Docker;
use bollard::query_parameters::EventsOptionsBuilder;
use futures_util::StreamExt;
use std::collections::HashMap;
#[tokio::main]
async fn main() {
let docker = Docker::connect_with_socket_defaults().unwrap();
let mut filters = HashMap::new();
filters.insert("type", vec!["container"]);
let options = EventsOptionsBuilder::default()
.since("1h")
.filters(&filters)
.build();
let mut stream = docker.events(Some(options));
while let Some(event) = stream.next().await {
match event {
Ok(msg) => println!("Event: {:?} {:?}", msg.typ, msg.action),
Err(e) => eprintln!("Error: {e}"),
}
}
}
Error Handling
All system methods return Result<_, bollard::errors::Error>. The most common errors are:
| Error variant | Cause |
|---|
DockerResponseServerError { status_code, message } | The daemon returned a non-2xx HTTP status. |
RequestTimeoutError | The request exceeded the client timeout (default 2 minutes). |
IOError | Underlying socket or pipe I/O failure. |
Call docker.ping().await at application startup to surface connectivity problems early, before attempting heavier API calls.
