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 treats Podman as a first-class container runtime alongside Docker. The connect_with_podman_defaults method performs automatic socket discovery for both rootless and system (rootful) Podman installations, so you rarely need to specify socket paths manually.
connect_with_podman_defaults is currently Unix only. The pipe feature flag (enabled by default) is required.

​
Docker::connect_with_podman_defaults

Probes a prioritised list of well-known socket locations and connects to the first one that exists on the filesystem. 
use bollard::Docker;

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

​
Function signature

#[cfg(unix)]
pub fn connect_with_podman_defaults() -> Result<Docker, Error>

​
Socket Discovery Order

The method walks through the following candidates in order and uses the first socket that exists:
1

$DOCKER_HOST (explicit override)

If the DOCKER_HOST environment variable is set and starts with unix://, it is used directly — no filesystem probe is performed.
export DOCKER_HOST=unix:///run/user/1000/podman/podman.sock
2

$XDG_RUNTIME_DIR/podman/podman.sock (rootless, preferred)

The canonical rootless socket. Requires XDG_RUNTIME_DIR to be set — most systemd-based Linux distributions set this automatically at login.
$XDG_RUNTIME_DIR/podman/podman.sock
3

/run/user/$UID/podman/podman.sock (rootless fallback)

Constructed at runtime by substituting the current process’s UID. Used when XDG_RUNTIME_DIR is unset or does not contain a Podman socket.
/run/user/1000/podman/podman.sock
4

/run/podman/podman.sock (system / rootful)

The system-wide Podman socket, typically owned by root or the podman group. Requires appropriate group membership or sudo.
/run/podman/podman.sock
5

/var/run/docker.sock (Docker fallback)

Falls back to the standard Docker socket if none of the Podman sockets exist. This allows the same code to work on hosts that run Docker instead of Podman.
/var/run/docker.sock

​
Feature Flag

This method requires the pipe feature, which is enabled by default. No extra configuration is needed for most projects.
bollard = "*"   # pipe is on by default
To use a minimal build with only Podman socket support:
bollard = { version = "*", default-features = false, features = ["pipe"] }

​
Overriding the Socket at Runtime

Set DOCKER_HOST to a unix:// URL to bypass auto-discovery entirely. This is the recommended way to pin a specific Podman socket — for example, when running multiple Podman instances or in CI environments.
# Rootless socket for a specific user
export DOCKER_HOST=unix:///run/user/1000/podman/podman.sock

# System (rootful) socket
export DOCKER_HOST=unix:///run/podman/podman.sock

​
Complete Example

1

Start the Podman socket service

On systemd-based Linux distributions, enable the Podman socket for your user:
systemctl --user enable --now podman.socket
Or for the system-wide (rootful) socket:
sudo systemctl enable --now podman.socket
2

Add Bollard to Cargo.toml

[dependencies]
bollard = "*"
tokio = { version = "1", features = ["full"] }
3

Connect with auto-discovery

use bollard::Docker;

#[tokio::main]
async fn main() {
    let docker = Docker::connect_with_podman_defaults()
        .expect("Failed to connect to Podman");

    let version = docker.version().await.unwrap();
    println!("Podman version: {:?}", version.version);
}
4

Or override the socket explicitly

export DOCKER_HOST=unix:///run/user/1000/podman/podman.sock
cargo run

use bollard::Docker;

#[tokio::main]
async fn main() {
    // DOCKER_HOST is honoured automatically by connect_with_podman_defaults
    let docker = Docker::connect_with_podman_defaults()
        .expect("Failed to connect to Podman");

    let version = docker.version().await.unwrap();
    println!("Podman version: {:?}", version.version);
}

​
Podman vs Docker Socket

Because Bollard uses the Docker-compatible REST API that Podman exposes, the Docker struct works identically against both runtimes. connect_with_podman_defaults simply ensures the right socket is selected on Podman-only hosts. All other Bollard APIs — containers, images, volumes, networks — work without modification.

connect_with_podman_defaults

Best choice when targeting hosts that may run Podman, rootless Podman, or a Podman-to-Docker socket shim. Performs automatic discovery with Docker fallback.

connect_with_local_defaults

Best choice when targeting standard Docker installations. Uses DOCKER_HOST / context resolution and defaults to /var/run/docker.sock.

Build docs developers (and LLMs) love

Get started for freeTalk to us