Skip to main content

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.

Bollard provides a full set of async image management methods on the Docker struct. Pull, build, inspect, tag, push, and export operations are all covered. Build and pull operations return a Stream of progress events that you can consume incrementally.

​
Pulling an Image

create_image pulls (or imports) an image from a registry. It returns a Stream<Item = Result<CreateImageInfo, Error>> so you can observe download progress layer by layer. 
use bollard::Docker;
use bollard::query_parameters::CreateImageOptionsBuilder;
use futures_util::TryStreamExt;

let docker = Docker::connect_with_socket_defaults().unwrap();

docker
    .create_image(
        Some(
            CreateImageOptionsBuilder::default()
                .from_image("alpine:3")
                .build(),
        ),
        None,
        None,
    )
    .try_collect::<Vec<_>>()
    .await?;
The third argument to create_image is an optional DockerCredentials struct for pulling from private registries.

​
Listing Images

list_images returns Vec<ImageSummary>. Filter by dangling, label, or other keys. 
use bollard::Docker;
use bollard::query_parameters::ListImagesOptionsBuilder;
use std::collections::HashMap;

let docker = Docker::connect_with_socket_defaults().unwrap();

let mut filters = HashMap::new();
filters.insert("dangling", vec!["true"]);

let images = docker
    .list_images(Some(
        ListImagesOptionsBuilder::default()
            .all(true)
            .filters(&filters)
            .build(),
    ))
    .await?;

for img in &images {
    println!("{:?} — {}", img.repo_tags, img.size);
}

​
Inspecting an Image

inspect_image returns ImageInspect with full metadata: architecture, OS, layers, exposed ports, and more. 
use bollard::Docker;

let docker = Docker::connect_with_socket_defaults().unwrap();

let info = docker.inspect_image("alpine:3").await?;
println!("Architecture: {:?}", info.architecture);
println!("OS: {:?}", info.os);
println!("Layers: {:?}", info.root_fs.and_then(|r| r.layers));

​
Building an Image

build_image streams BuildInfo events. Provide a BuildImageOptions, optional registry credentials, and a tar archive body. 
use bollard::Docker;
use bollard::query_parameters::BuildImageOptionsBuilder;
use bollard::body_full;
use futures_util::TryStreamExt;
use std::fs::File;
use std::io::Read;

let docker = Docker::connect_with_socket_defaults().unwrap();

let options = BuildImageOptionsBuilder::default()
    .dockerfile("Dockerfile")
    .t("my-image:latest")
    .rm(true)
    .build();

let mut file = File::open("tarball.tar.gz").unwrap();
let mut contents = Vec::new();
file.read_to_end(&mut contents).unwrap();

let build_stream = docker.build_image(options, None, Some(body_full(contents.into())));

build_stream
    .try_for_each(|info| async move {
        if let Some(stream) = info.stream {
            print!("{stream}");
        }
        Ok(())
    })
    .await?;
For advanced builds using BuildKit (multi-stage caching, secrets, SSH forwarding), enable the buildkit_providerless feature and set version(BuilderVersion::BuilderBuildKit) in your options. See the BuildKit guide for details.

​
Tagging an Image

Tag an existing image to add it to a repository under a new name or tag. 
use bollard::Docker;
use bollard::query_parameters::TagImageOptionsBuilder;

let docker = Docker::connect_with_socket_defaults().unwrap();

docker
    .tag_image(
        "my-image:latest",
        Some(
            TagImageOptionsBuilder::default()
                .repo("registry.example.com/my-image")
                .tag("v1.0.1")
                .build(),
        ),
    )
    .await?;

​
Pushing an Image

push_image returns a Stream<Item = Result<PushImageInfo, Error>>. Consume it fully to ensure the push completes. 
use bollard::Docker;
use bollard::auth::DockerCredentials;
use bollard::query_parameters::PushImageOptionsBuilder;
use futures_util::TryStreamExt;

let docker = Docker::connect_with_socket_defaults().unwrap();

let credentials = Some(DockerCredentials {
    username: Some("myuser".to_string()),
    password: Some("mypassword".to_string()),
    ..Default::default()
});

docker
    .push_image(
        "registry.example.com/my-image",
        Some(PushImageOptionsBuilder::default().tag("v1.0.1").build()),
        credentials,
    )
    .try_collect::<Vec<_>>()
    .await?;
Always drive the stream to completion with .try_collect() or .try_for_each(). Dropping it early cancels the push.

​
Exporting and Importing Images

use bollard::Docker;
use futures_util::TryStreamExt;
use tokio::io::AsyncWriteExt;
use tokio::fs::File;

let docker = Docker::connect_with_socket_defaults().unwrap();

let mut file = File::create("alpine.tar").await?;
let mut stream = docker.export_image("alpine:3");

while let Some(chunk) = stream.try_next().await? {
    file.write_all(&chunk).await?;
}

​
Removing an Image

use bollard::Docker;
use bollard::query_parameters::RemoveImageOptionsBuilder;

let docker = Docker::connect_with_socket_defaults().unwrap();

let deleted = docker
    .remove_image(
        "my-image:latest",
        Some(
            RemoveImageOptionsBuilder::default()
                .force(false)
                .noprune(false)
                .build(),
        ),
        None, // optional DockerCredentials
    )
    .await?;

for d in &deleted {
    println!("{:?}", d);
}

​
Pruning Unused Images

use bollard::Docker;
use bollard::query_parameters::PruneImagesOptionsBuilder;
use std::collections::HashMap;

let docker = Docker::connect_with_socket_defaults().unwrap();

let mut filters = HashMap::new();
filters.insert("until", vec!["24h"]);

let result = docker
    .prune_images(Some(
        PruneImagesOptionsBuilder::default()
            .filters(&filters)
            .build(),
    ))
    .await?;

println!(
    "Reclaimed: {:?} bytes",
    result.space_reclaimed
);

​
Searching Docker Hub

use bollard::Docker;
use bollard::query_parameters::SearchImagesOptionsBuilder;

let docker = Docker::connect_with_socket_defaults().unwrap();

// SearchImagesOptions requires a `term` field
let results = docker
    .search_images(
        bollard::query_parameters::SearchImagesOptionsBuilder::default()
            .term("alpine")
            .limit(5)
            .build(),
    )
    .await?;

for item in &results {
    println!("{} — stars: {:?}", item.name.as_deref().unwrap_or("?"), item.star_count);
}

​
Committing a Container as an Image

commit_container snapshots the filesystem of a running or stopped container and saves it as a new image. 
use bollard::Docker;
use bollard::models::ContainerConfig;
use bollard::query_parameters::CommitContainerOptionsBuilder;

let docker = Docker::connect_with_socket_defaults().unwrap();

let options = CommitContainerOptionsBuilder::default()
    .container("my-app")
    .repo("my-snapshot")
    .tag("v2")
    .pause(true)
    .build();

let id = docker
    .commit_container(options, ContainerConfig::default())
    .await?;

println!("New image ID: {:?}", id.id);

Build docs developers (and LLMs) love

Get started for freeTalk to us