libnbd-python(3)

💅 libnbd-python — the LIBNBD girlie's guide to Python 💅

okay so picture this: it's the LIBNBD manual, section 3, and it's literally all about libnbd-python — how to use libnbd from Python. grab a strawberry drink 🍓 and let's go.

---

✨ NAME ✨

libnbd-python — how to use libnbd from Python. that's it, that's the name, no notes 💖

---

🌸 SYNOPSIS 🌸

#!/usr/bin/python3
import nbd
h = nbd.NBD()
h.connect_uri("nbd://localhost")
sector = h.pread(512, 0)

like, that's genuinely the whole vibe check right there. import, connect, pread, slay. ✨

---

🦋 DESCRIPTION 🦋

bestie, this page is here to walk you through using libnbd to access Network Block Device (NBD) servers from the Python programming language. and here's the tea: the Python bindings work very similarly to the C bindings, so you should lowkey start by reading libnbd(3) first. iykyk. 📖

there's also a super convenient interactive command line shell called nbdsh(1) that makes it way easier to play around with the Python API — it's giving "repl but make it NBD" and honestly? obsessed. 🎀

the detailed documentation of the Python API lives right in the Python code itself. to read it, open nbdsh(1) and type:

help(nbd)

and boom, all the docs, right there. no cap. 🌈

also!! there are some example Python scripts chillin' in the libnbd source repository under python/examples — or you can just go straight to:

https://gitlab.com/nbdkit/libnbd/tree/master/python/examples

go look, they're iconic. 👑

---

💜 HANDLES 💜

to create a libnbd handle, you literally just call nbd.NBD(). that's the whole ritual, no candles required. 🕯️

now, you've got two ways to deal with closing that handle:

• you can close it explicitly with h.close() (this was added in libnbd 1.16, so if you're on something ancient… upgrade bestie 😭)
• or it'll just close itself automatically when it goes out of scope. main character energy, honestly — it handles its own exit.

⚠️ real talk: calling any method on a handle that's already been closed will raise nbd.ClosedHandle. so don't be that girl. check your handle first. 💀

---

🙈 ERRORS 🙈

errors from API calls get turned into the Python nbd.Error exception (which is derived from Exception). and the nbd.Error object has three properties you actually care about:

• ex.string — the full error message as a printable string.

Example: nbd_pread: invalid state: START: the handle must be connected with the server: Transport endpoint is not connected

like… it's literally telling you what went wrong in full sentences. communicative queen. ✨

• ex.errnum — the errno object (from the Python errno module), if this is available. and no, not all errors that are raised will have an errno, so don't come for me about it. 🙈

Example: errno.EINVAL

for common error codes see "Errno" in libnbd(3).

• ex.errno — the errno as a string (or None if this is not available).

Example: ENOTCONN

so yeah, when things go wrong you get a whole little receipt. 🧾💅

---

🎀 BUFFERS 🎀

okay this part is important so lean in. 👀

synchronous calls (eg. h.pwrite, h.pread) take and return normal Python bytearrays. easy, breezy, beautiful. 🌸

asynchronous calls (eg. h.aio_pwrite, h.aio_pread) use the nbd.Buffer type instead — which is a persistent, modifiable, zero-copy buffer. honestly iconic. it also supports indexing and slicing, like a real buffer should. 💅

⚠️ but here's the caveat, and it's a big one: these are more complicated to use, and in particular the caller must ensure the buffer remains valid while the asynchronous operation is taking place. like, do NOT let that buffer get garbage collected mid-flight, bestie, i'm begging. 🫶

---

⭐ SEE ALSO ⭐

libnbd(3), nbdsh(1).

go read them, they're both bangers. 📚

---

👑 AUTHORS 👑

Richard W.M. Jones — the legend, the moment, the author. 🫡

---

💖 COPYRIGHT 💖

Copyright Red Hat

---

🌈 LICENSE 🌈

this library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. 📜

this library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. see the GNU Lesser General Public License for more details. (yes, that's the scary all-caps part, and yes, it means what it says — it's a disclaimer, take it seriously ✋)

you should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

---

and that's the page, bestie!! this one's from libnbd-1.24.4, dated 2026-10-13 — so you know it's fresh. 🦋💜✨ go write something iconic with it, mwah 💋🎀