{"id":9223,"library":"pylspci","title":"pylspci - PCI Device Parser","description":"pylspci is a Python library that provides a convenient interface to parse the output of the `lspci -mmnn` command, transforming it into Python objects. It can be used to query PCI devices on local or remote UNIX machines. The current version is 0.4.3, with an infrequent release cadence, though a 0.5.0 release candidate was published in January 2025.","status":"active","version":"0.4.3","language":"en","source_language":"en","source_url":"https://github.com/YADRO-KNS/py-lspci","tags":["pci","lspci","hardware","system information","parser"],"install":[{"cmd":"pip install pylspci","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Provides the `lspci` command-line tool, which `pylspci` parses. Must be installed on the target machine (local or remote).","package":"pciutils","optional":false}],"imports":[{"symbol":"ScannerPCI","correct":"from pylspci import ScannerPCI"}],"quickstart":{"code":"import os\nfrom pylspci import ScannerPCI\n\n# Example for a remote connection, using environment variables for credentials\n# For local scan, if current user can run lspci without sudo, password can be omitted.\n# If local scan requires sudo, provide password or ensure user has sudo access without password.\n\n# Replace with your target IP, username, and ensure PCI_PASSWORD is set in your environment\ntarget_ip = os.environ.get('PCI_HOST_IP', '127.0.0.1')\nusername = os.environ.get('PCI_USERNAME', 'root')\npassword = os.environ.get('PCI_PASSWORD', '')\n\ntry:\n    # Connect to the target machine\n    # For local machine requiring sudo, you'd typically pass ip='127.0.0.1', password=password\n    # For remote, provide IP, username, and password.\n    if target_ip == '127.0.0.1' and not password: # Attempt local without password if not explicitly set\n        scanner = ScannerPCI(ip=target_ip)\n    elif target_ip == '127.0.0.1': # Local with password\n        scanner = ScannerPCI(ip=target_ip, password=password)\n    else: # Remote connection\n        scanner = ScannerPCI(ip=target_ip, username=username, password=password)\n\n    # Select all PCI devices\n    devices = scanner.select()\n\n    print(f\"Found {len(devices)} PCI devices:\")\n    for device in devices:\n        print(f\"  - {device.slot}: {device.vendor_name} {device.device_name} ({device.device_class_name})\")\n\n    # Example: Find all network controllers\n    network_controllers = scanner.select(device_class_name='*Ethernet*')\n    if network_controllers:\n        print(\"\\nNetwork Controllers:\")\n        for nc in network_controllers:\n            print(f\"  - {nc.slot}: {nc.vendor_name} {nc.device_name}\")\n    else:\n        print(\"\\nNo network controllers found.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"This quickstart demonstrates how to connect to a target (local or remote) using `pylspci.ScannerPCI` and then retrieve and filter PCI devices. It uses environment variables for sensitive credentials in remote connection examples. Ensure the target machine has `pciutils` installed and appropriate network access and authentication are configured."},"warnings":[{"fix":"Ensure the user executing the Python script has necessary permissions to run `lspci` (e.g., password-less sudo) or provide credentials to `ScannerPCI` for elevated access. For remote access, the user specified must have sudo privileges on the target machine.","message":"The underlying `lspci` command requires `sudo` privileges for full functionality and especially for accessing detailed configuration space information. If `pylspci` is run without sufficient permissions, it may return incomplete data or fail to connect. For local scans, provide a password if the user is not root; for remote scans, ensure the user has `sudo` access.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Avoid direct `lspci -xxx` commands. When using `pylspci`, be aware of the underlying `lspci` behavior. Report any unexpected system instability to `pylspci` developers if it occurs during normal operation.","message":"Using extremely verbose `lspci` options (like `lspci -xxx` for hexadecimal dump of configuration space) can, in rare cases, crash certain PCI devices, potentially leading to system instability or data loss. While `pylspci` primarily uses `lspci -mmnn`, direct interaction with `lspci` or future `pylspci` features that expose more verbose modes should be handled with caution.","severity":"gotcha","affected_versions":"All versions (inherent to `lspci` utility)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure the user running the `pylspci` script has root privileges or sufficient permissions to access `/sys/bus/pci/devices`. For local machines, try running with `sudo python your_script.py`. For remote, confirm the `username` and `password` provided to `ScannerPCI` have `sudo` access on the target. If the issue persists, it might be a hardware-specific anomaly that can often be safely ignored if no functional problems are observed.","cause":"This error message originates from the underlying `lspci` utility, indicating it failed to read information from a specific PCI device path in `/sys/bus/pci/devices`. This can be due to insufficient permissions, hardware-specific quirks, or a device not responding correctly.","error":"pcilib: Error reading /sys/bus/pci/devices/0000:00:08.3/label: Ope..."},{"fix":"Verify the `username` and `password` passed to `ScannerPCI` are correct for the target `ip`. Ensure the specified user has permissions to run `sudo lspci` without requiring additional password prompts on the remote host, or that the provided password correctly authenticates for `sudo` if needed.","cause":"The provided username or password for the remote connection is incorrect, or the user does not have `sudo` privileges on the target machine to execute `lspci`.","error":"pylspci.exceptions.ConnectionException: Connection to 192.168.1.1 failed: Authentication failed."}]}