pylxd

2.4.1 verified Fri May 01 auth: no python

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.

pip install pylxd

Common errors

error pylxd.exceptions.LXDAPIException: 'trust' ↓

cause 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.

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

cause 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.

error pylxd.exceptions.LXDAPIException: 'not found' ↓

cause 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.

Warnings

breaking In 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').

breaking Storage 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.

deprecated The 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.

gotcha When 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')

gotcha Instance 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'}}

Imports

Client
wrong
```
import pylxd
```
correct
```
from pylxd import Client
```
Client is the main entry point; pylxd module itself does not expose Client directly.
Client
wrong
```
from pylxd.client import Client
```
correct
```
from pylxd import Client
```
Client is exposed at the package level; importing from pylxd.client is an internal detail and may break.

Quickstart

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}")