{"id":7115,"library":"cpuset-py3","title":"CPUSet for Python 3","description":"cpuset-py3 is a Python 3 compatible fork of the original cpuset library, providing functionalities to query and manipulate CPU sets (processor affinity) on Linux systems. It allows creating, modifying, and applying CPU sets to processes and threads, facilitating fine-grained control over CPU core usage. The current version is 1.0.2, and it's maintained on an as-needed basis rather than a strict release cadence.","status":"active","version":"1.0.2","language":"en","source_language":"en","source_url":"https://github.com/parttimenerd/cpuset","tags":["cpu affinity","cpuset","linux","performance","system","process management"],"install":[{"cmd":"pip install cpuset-py3","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"While `from cpuset import CPUSet` works for the class, many other core functions like `set_cpuset_for_current_process` are directly under the `cpuset` module, making `import cpuset` the more holistic and common usage pattern.","wrong":"from cpuset import CPUSet","symbol":"CPUSet","correct":"import cpuset; s = cpuset.CPUSet()"},{"symbol":"set_cpuset_for_current_process","correct":"import cpuset; cpuset.set_cpuset_for_current_process(...)"}],"quickstart":{"code":"import cpuset\nimport platform\n\nprint(f\"Running on OS: {platform.system()}\\n\")\n\n# Create a new empty cpuset\ns = cpuset.CPUSet()\ns.add_cpu(0)\ns.add_cpu(1)\ns.add_cpu(2)\nprint(f\"Created CPUSet (0,1,2): {s.as_list()}\")\nprint(f\"As string: {s.as_str()}\")\nprint(f\"As canonical string: {s.as_canonical_str()}\") # will be \"0-2\"\nprint(f\"As bitmask: {hex(s.as_bitmask())}\") # 0x7\n\n# Create from a string representation\ns_from_str = cpuset.CPUSet(\"0-3,5\")\nprint(f\"\\nCPUSet from string '0-3,5': {s_from_str.as_list()}\")\n\nif platform.system() == \"Linux\":\n    print(\"\\nAttempting to query current process affinity (Linux-only):\")\n    try:\n        current_affinity = cpuset.get_cpuset_for_current_process()\n        print(f\"  Current process affinity: {current_affinity.as_list()}\")\n\n        # Uncomment to attempt setting affinity (requires appropriate permissions):\n        # print(f\"  Attempting to set process affinity to {s.as_list()}...\")\n        # cpuset.set_cpuset_for_current_process(s)\n        # updated_affinity = cpuset.get_cpuset_for_current_process()\n        # print(f\"  Updated process affinity: {updated_affinity.as_list()}\")\n\n    except PermissionError:\n        print(\"  Permission denied to get/set process affinity. Try running with sudo or check capabilities.\")\n    except Exception as e:\n        print(f\"  An error occurred during system affinity call: {e}\")\nelse:\n    print(\"\\nSystem affinity functions (get/set) are only available on Linux.\")\n\nprint(\"\\nOperations on CPUSet objects are generally platform-independent:\")\ns_union = s | cpuset.CPUSet(\"3-4\")\nprint(f\"Union (0-2 | 3-4): {s_union.as_list()}\") # [0,1,2,3,4]\n\ns_intersect = s & cpuset.CPUSet(\"1-3\")\nprint(f\"Intersection (0-2 & 1-3): {s_intersect.as_list()}\") # [1,2]\n","lang":"python","description":"This quickstart demonstrates how to create and manipulate `CPUSet` objects. It also shows how to query the current process's affinity on Linux, with a note about the permissions often required for setting affinity."},"warnings":[{"fix":"Ensure your application runs on a Linux environment when utilizing system affinity features.","message":"This library is designed specifically for Linux systems. Functions for querying and setting CPU affinity (`get_cpuset_for_current_process`, `set_cpuset_for_current_process`, etc.) will not function correctly or might raise errors on other operating systems like macOS or Windows.","severity":"gotcha","affected_versions":"All"},{"fix":"Run your script with `sudo` (e.g., `sudo python your_script.py`) or configure the executing user/process with the necessary Linux capabilities.","message":"Setting CPU affinity for processes or threads often requires elevated privileges (e.g., root access or specific Linux capabilities like CAP_SYS_NICE). Operations like `set_cpuset_for_current_process` might fail with `PermissionError` if not run with sufficient permissions.","severity":"gotcha","affected_versions":"All"},{"fix":"Always use `pip install cpuset-py3`. If you accidentally installed `cpuset`, uninstall it first with `pip uninstall cpuset`.","message":"Be careful to install `cpuset-py3` for Python 3 compatibility. There is an older, incompatible package named `cpuset` on PyPI which is intended for Python 2 and will cause `AttributeError` or unexpected behavior in Python 3 environments.","severity":"gotcha","affected_versions":"All"},{"fix":"For human-readable output, prefer `as_list()` or `as_canonical_str()`. Only use `as_bitmask()` when direct bitwise operations or kernel-level interfaces require it.","message":"The `as_bitmask()` method returns an integer bitmask where each bit corresponds to a CPU ID. For larger or sparsely populated CPU sets, interpreting this raw bitmask can be complex or unintuitive compared to list or string representations.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the library using `pip install cpuset-py3`.","cause":"The `cpuset-py3` package has not been installed, or the Python interpreter is not in an environment where it's installed.","error":"ModuleNotFoundError: No module named 'cpuset'"},{"fix":"Run the Python script with root privileges (e.g., `sudo python your_script.py`) or ensure the executing user/process has the `CAP_SYS_NICE` capability.","cause":"Attempting to change process or thread CPU affinity without sufficient operating system permissions.","error":"PermissionError: [Errno 1] Operation not permitted: 'cpuset'"},{"fix":"Uninstall the incorrect package (`pip uninstall cpuset`) and then install the correct one (`pip install cpuset-py3`).","cause":"You likely installed the old `cpuset` (Python 2) package instead of `cpuset-py3`, which has a different internal structure or is incompatible with Python 3.","error":"AttributeError: module 'cpuset' has no attribute 'CPUSet'"}]}