pylxd

library2.4.1pypypi✓ verified 86d ago

pylxd is a Python library for interacting with the LXD REST API, providing a client for managing containers, virtual machines, images, networks, storage, and profiles on LXD instances. Current version is 2.4.1, requiring Python >=3.10. The library is maintained by Canonical and follows the LXD API changes. Releases happen irregularly, driven by LXD updates and bug fixes.

devops http-networking

pip install pylxd

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · PYLXD

pylxd

devopspythonv2.4.1

Install

3.2s avg

Import

848ms

Disk

39MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.4.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.886s · 40.1MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.2s · import 0.810s · 41MB

39MB installed

● package 39MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Client

✓ from pylxd import Client

✗ import pylxd

Client is the main entry point; pylxd module itself does not expose Client directly.

Client

✓ from pylxd import Client

✗ from pylxd.client import Client

Client is exposed at the package level; importing from pylxd.client is an internal detail and may break.

Connect to LXD, list instances, create and start a container.

from pylxd import Client # Connect to local LXD (via Unix socket) client = Client() # Or connect to remote LXD with password # client = Client(endpoint='https://10.0.0.1:8443', cert=('/path/to/client.crt', '/path/to/client.key'), verify=True) # client.authenticate('password') # List instances instances = client.instances.all() for instance in instances: print(instance.name, instance.status) # Create a container config = {'name': 'my-container', 'source': {'type': 'image', 'alias': 'ubuntu/22.04'}} container = client.instances.create(config, wait=True) print(f"Created {container.name}") # Start container container.start(wait=True) print(f"{container.name} is {container.status}")

Debug

Known issues

breakingIn pylxd 2.3.8 and later, the /1.0/containers and /1.0/virtual-machines endpoints are removed; all operations now use /1.0/instances. Code that relied on container-specific endpoints (e.g., client.containers) may break.

fix

Use client.instances instead of client.containers or client.virtual_machines. The Instance model now handles both types; set instance type in create config via 'type' key (e.g., 'container' or 'virtual-machine').

affects: >=2.3.8

breakingStorage and profile operations became asynchronous in LXD, requiring pylxd 2.3.7+. Some methods that previously returned immediately now return an operation object that must be waited on.

fix

Use wait=True or call client.operations.wait(operation) after operations like storage pool creation or profile update. Check the returned Operation object for status.

affects: >=2.3.7

deprecatedThe requests-unixsocket library (used for local socket connections) is incompatible with requests 2.32.0+. As of pylxd 2.3.4, the library pins requests <2.32.0, but future versions may break.

fix

Upgrade to pylxd >=2.3.4, which restricts requests version. If you must use newer requests, consider using an HTTPClient adapter or switch to TCP endpoint.

affects: <2.3.4

gotchaWhen connecting to a remote LXD with password authentication, you must call client.authenticate(password) after creating the client. The password is not passed in the constructor.

fix

client = Client(endpoint='https://...', cert=('cert.pem', 'key.pem')); client.authenticate('mypassword')

affects: all

gotchaInstance creation uses the /1.0/instances endpoint. The config dict must include a 'type' key (e.g., 'container' or 'virtual-machine') to specify the instance type. Omitting it may default to container but is ambiguous.

fix

config = {'name': 'vm1', 'type': 'virtual-machine', 'source': {'type': 'image', 'alias': 'ubuntu/22.04'}}

affects: >=2.3.8

Errors

Common errors & fixes

pylxd.exceptions.LXDAPIException: 'trust'

Authentication failed due to invalid certificate or missing trust relationship.

fix

Ensure the client certificate is added to the LXD trust store: `lxc config trust add client.crt` on the LXD host.

requests.exceptions.ConnectionError: ('Connection aborted.', PermissionError(13, 'Permission denied'))

The LXD Unix socket is not accessible to the current user (not in lxd group).

fix

Add user to the lxd group: `sudo usermod -aG lxd $USER` then log out and back in.

pylxd.exceptions.LXDAPIException: 'not found'

The requested resource (e.g., instance, image) does not exist on the LXD server.

fix

Verify the resource name/alias exists. For images, use `lxc image list` to check available aliases.

Upgrade

Version history

2.4.1latest on PyPI · released Apr 6, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/canonical/pylxd ↗

packagehttps://pypi.org/project/pylxd/ ↗

homepagehttps://ubuntu.com/lxd ↗

docshttps://pylxd.readthedocs.io/en/latest/ ↗