{"library":"pyserial","title":"PySerial","description":"PySerial is a widely used, cross-platform Python library that provides essential functionality for serial port communication. It allows Python scripts to easily interact with a broad range of hardware devices, including microcontrollers (like Arduino and Raspberry Pi), GPS modules, industrial sensors, and other serial-enabled peripherals across Windows, Linux, and macOS. Currently at version 3.5, PySerial maintains an active development cycle, releasing bug fixes and minor feature updates periodically.","status":"active","version":"3.5","language":"en","source_language":"en","source_url":"https://github.com/pyserial/pyserial","tags":["serial communication","hardware","RS232","USB-to-Serial","microcontroller"],"install":[{"cmd":"pip install pyserial","lang":"bash","label":"Install latest stable version"}],"dependencies":[{"reason":"Required for asynchronous (async/await) serial port operations, as this functionality was moved out of the main PySerial library.","package":"pyserial-asyncio","optional":true}],"imports":[{"note":"The primary class for serial communication is `Serial`, typically imported from the `serial` module, not directly from `pyserial`.","wrong":"from pyserial import Serial","symbol":"Serial","correct":"import serial\nser = serial.Serial(...)"},{"note":"Port listing utilities are located within `serial.tools.list_ports`.","wrong":"import serial.list_ports","symbol":"list_ports","correct":"from serial.tools import list_ports"}],"quickstart":{"code":"import serial\nimport time\n\n# Configure the serial port\n# Replace 'COM3' with your actual serial port ('/dev/ttyUSB0' on Linux, 'COMx' on Windows)\n# Ensure baudrate matches your device\nser = serial.Serial(\n    port='COM_PORT_HERE', \n    baudrate=9600, \n    bytesize=serial.EIGHTBITS, \n    parity=serial.PARITY_NONE, \n    stopbits=serial.STOPBITS_ONE,\n    timeout=1 # Read timeout in seconds\n)\n\ntry:\n    if not ser.is_open:\n        ser.open()\n    print(f\"Serial port {ser.name} opened successfully.\")\n\n    # Write data (must be bytes in Python 3)\n    message_to_send = b\"Hello, device!\\n\"\n    ser.write(message_to_send)\n    print(f\"Sent: {message_to_send.decode().strip()}\")\n\n    time.sleep(0.1) # Give the device some time to respond\n\n    # Read data\n    received_data = ser.readline() # Reads until newline or timeout\n    if received_data:\n        print(f\"Received: {received_data.decode().strip()}\")\n    else:\n        print(\"No data received within timeout.\")\n\nexcept serial.SerialException as e:\n    print(f\"Serial port error: {e}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\nfinally:\n    if ser.is_open:\n        ser.close()\n        print(\"Serial port closed.\")\n","lang":"python","description":"This quickstart demonstrates how to open, configure, write to, and read from a serial port using PySerial. It includes error handling and ensures the port is closed. Remember to replace `'COM_PORT_HERE'` with your actual serial port name and adjust `baudrate` as needed for your device. Data sent and received must be handled as `bytes` in Python 3."},"warnings":[{"fix":"Ensure all data written to the serial port is encoded as `bytes` (e.g., `b'your data'` or `my_string.encode('utf-8')`). Data read from the port will also be `bytes` and may need to be decoded (`received_data.decode('utf-8')`).","message":"Python 2.x vs. Python 3.x String Handling: PySerial 3.x requires `bytes` objects for write operations (e.g., `ser.write(b'data')`). Direct string literals (`'data'`) will cause errors in Python 3.x, unlike Python 2.x where strings were byte sequences.","severity":"breaking","affected_versions":"3.0+"},{"fix":"For asynchronous serial communication, install the separate `pyserial-asyncio` library (`pip install pyserial-asyncio`) and use its API.","message":"Removal of `serial.aio`: Asynchronous I/O support (`serial.aio`) was removed from the core PySerial library in version 3.2.1.","severity":"breaking","affected_versions":"3.2.1+"},{"fix":"Use `ser.in_waiting` (integer, number of bytes in input buffer) instead of `ser.inWaiting()` and `ser.is_open` (boolean) instead of `ser.isOpen()`.","message":"Deprecated methods `inWaiting()` and `isOpen()`: These methods were deprecated in favor of more Pythonic attribute names.","severity":"deprecated","affected_versions":"3.0+"},{"fix":"Always set a `timeout` parameter (e.g., `timeout=1`) when initializing `serial.Serial`. This will cause `readline()` to return after the specified duration if no data or newline is received.","message":"`readline()` without a timeout can block indefinitely: If a timeout is not set on the `Serial` object, `readline()` will block until a newline character is received, which can lead to unresponsive applications if the device does not send one.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use `serial.tools.list_ports` module for port enumeration. For example, `from serial.tools import list_ports; ports = list_ports.comports()`.","message":"Removal of `serial.device()`: The function `serial.device()` for listing ports was removed.","severity":"breaking","affected_versions":"3.0+"}],"env_vars":null,"last_verified":"2026-04-06T00:00:00.000Z","next_check":"2026-07-05T00:00:00.000Z"}