{"id":13566846,"url":"https://github.com/truenas/py-SMART","last_synced_at":"2025-04-04T00:32:21.157Z","repository":{"id":36325985,"uuid":"40630667","full_name":"truenas/py-SMART","owner":"truenas","description":"Wrapper for smartctl (smartmontools)","archived":false,"fork":false,"pushed_at":"2025-02-17T13:37:59.000Z","size":685,"stargazers_count":84,"open_issues_count":6,"forks_count":36,"subscribers_count":25,"default_branch":"master","last_synced_at":"2025-03-17T19:55:36.559Z","etag":null,"topics":["python","smartctl","smartmontools","wrapper"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/truenas.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-08-13T00:21:28.000Z","updated_at":"2025-03-13T20:37:22.000Z","dependencies_parsed_at":"2023-02-14T06:46:02.493Z","dependency_job_id":"e6765606-e5a7-461b-9abb-d0f3ee15ce93","html_url":"https://github.com/truenas/py-SMART","commit_stats":{"total_commits":221,"total_committers":20,"mean_commits":11.05,"dds":0.4072398190045249,"last_synced_commit":"304a970ac718fb9f0344624ce629e2489c09fc1e"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/truenas%2Fpy-SMART","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/truenas%2Fpy-SMART/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/truenas%2Fpy-SMART/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/truenas%2Fpy-SMART/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/truenas","download_url":"https://codeload.github.com/truenas/py-SMART/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247103290,"owners_count":20884023,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["python","smartctl","smartmontools","wrapper"],"created_at":"2024-08-01T13:02:17.938Z","updated_at":"2025-04-04T00:32:21.149Z","avatar_url":"https://github.com/truenas.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"pySMART\n===========\n\n![](https://img.shields.io/pypi/v/pySMART?label=release)\n![](https://img.shields.io/pypi/pyversions/pySMART)\n[![Python Tests](https://github.com/truenas/py-SMART/actions/workflows/check.yml/badge.svg)](https://github.com/truenas/py-SMART/actions/workflows/check.yml)\n![](https://img.shields.io/github/actions/workflow/status/truenas/py-smart/publish-to-test-pypi.yml)\n![](https://img.shields.io/github/issues/truenas/py-smart)\n![](https://img.shields.io/github/issues-pr/truenas/py-smart)\n![](https://img.shields.io/pypi/dm/pysmart)\n\nCopyright (C) 2021-2025 [Rafael Leira](https://github.com/ralequi)\\\nCopyright (C) 2021 [Truenas team](https://www.truenas.com/)\\\nCopyright (C) 2015 Marc Herndon\n\npySMART is a simple Python wrapper for the ``smartctl`` component of\n``smartmontools``. It is officially compatible with Linux, Windows and FreeBSD,\nas long as smartctl is on the system path. Running with administrative rights\nis strongly recommended, as smartctl cannot accurately detect all device types\nor parse all SMART information without these permissions.\n\nWith only a device's name (ie: /dev/sda, pd0), the package will create a\n``Device`` object, populated with all relevant information about that\ndevice. The documented API can then be used to query this object for\ninformation, initiate self-tests, and perform other functions.\n\nUsage\n=====\nThe most common way to use pySMART is to create a logical representation of the\nphysical storage device that you would like to work with, as shown::\n\n\n```python\n\u003e\u003e\u003e from pySMART import Device\n\u003e\u003e\u003e sda = Device('/dev/sda')\n\u003e\u003e\u003e sda\n\u003cSATA device on /dev/sda mod:WDC WD5000AAKS-60Z1A0 sn:WD-WCAWFxxxxxxx\u003e\n```\n\n``Device`` class members can be accessed directly, and a number of helper methods\nare provided to retrieve information in bulk.  Some examples are shown below::\n\n```python\n\u003e\u003e\u003e sda.assessment  # Query the SMART self-assessment\n'PASS'\n\u003e\u003e\u003e sda.attributes[9]  # Query a single SMART attribute\n\u003cSMART Attribute 'Power_On_Hours' 068/000 raw:23644\u003e\n\u003e\u003e\u003e sda.all_attributes()  # Print the entire SMART attribute table\nID# ATTRIBUTE_NAME          CUR WST THR TYPE     UPDATED WHEN_FAIL    RAW\n  1 Raw_Read_Error_Rate     200 200 051 Pre-fail Always  -           0\n  3 Spin_Up_Time            141 140 021 Pre-fail Always  -           3908\n  4 Start_Stop_Count        098 098 000 Old_age  Always  -           2690\n  5 Reallocated_Sector_Ct   200 200 140 Pre-fail Always  -           0\n    ... # Edited for brevity\n199 UDMA_CRC_Error_Count    200 200 000 Old_age  Always  -           0\n200 Multi_Zone_Error_Rate   200 200 000 Old_age  Offline -           0\n\u003e\u003e\u003e sda.tests[0]  # Query the most recent self-test result\n\u003cSMART Self-test [Short offline|Completed without error] hrs:23734 LBA:-\u003e\n\u003e\u003e\u003e sda.all_selftests()  # Print the entire self-test log\nID Test_Description Status                        Left Hours  1st_Error@LBA\n 1 Short offline    Completed without error       00%  23734  -\n 2 Short offline    Completed without error       00%  23734  -\n   ... # Edited for brevity\n 7 Short offline    Completed without error       00%  23726  -\n 8 Short offline    Completed without error       00%  1      -\n```\n\nAlternatively, the package provides a ``DeviceList`` class. When instantiated,\nthis will auto-detect all local storage devices and create a list containing\none ``Device`` object for each detected storage device::\n\n```python\n\u003e\u003e\u003e from pySMART import DeviceList\n\u003e\u003e\u003e devlist = DeviceList()\n\u003e\u003e\u003e devlist\n\u003cDeviceList contents:\n\u003cSAT device on /dev/sdb mod:WDC WD20EADS-00R6B0 sn:WD-WCAVYxxxxxxx\u003e\n\u003cSAT device on /dev/sdc mod:WDC WD20EADS-00S2B0 sn:WD-WCAVYxxxxxxx\u003e\n\u003cCSMI device on /dev/csmi0,0 mod:WDC WD5000AAKS-60Z1A0 sn:WD-WCAWFxxxxxxx\u003e\n\u003e\n\u003e\u003e\u003e devlist.devices[0].attributes[5]  # Access Device data as above\n\u003cSMART Attribute 'Reallocated_Sector_Ct' 173/140 raw:214\u003e\n```\n\nIn the above cases if a new DeviceList is empty or a specific Device reports an\n\"UNKNOWN INTERFACE\", you are likely running without administrative privileges.\nOn POSIX systems, you can request smartctl is run as a superuser by setting the\nsudo attribute of the global SMARTCTL object to True. Note this may cause you\nto be prompted for a password.\n\n\n```python\n\u003e\u003e\u003e from pySMART import DeviceList\n\u003e\u003e\u003e from pySMART import Device\n\u003e\u003e\u003e sda = Device('/dev/sda')\n\u003e\u003e\u003e sda\n\u003cUNKNOWN INTERFACE device on /dev/sda mod:None sn:None\u003e\n\u003e\u003e\u003e devlist = DeviceList()\n\u003e\u003e\u003e devlist\n\u003cDeviceList contents:\n\u003e\n\u003e\u003e\u003e from pySMART import SMARTCTL\n\u003e\u003e\u003e SMARTCTL.sudo = True\n\u003e\u003e\u003e sda = Device('/dev/sda')\n\u003e\u003e\u003e sda\n[sudo] password for user:\n\u003cSAT device on /dev/sda mod:ST10000DM0004-1ZC101 sn:ZA20VNPT\u003e\n\u003e\u003e\u003e devlist = DeviceList()\n\u003e\u003e\u003e devlist\n\u003cDeviceList contents:\n\u003cNVME device on /dev/nvme0 mod:Sabrent Rocket 4.0 1TB sn:03850709185D88300410\u003e\n\u003cNVME device on /dev/nvme1 mod:Samsung SSD 970 EVO Plus 2TB sn:S59CNM0RB05028D\u003e\n\u003cNVME device on /dev/nvme2 mod:Samsung SSD 970 EVO Plus 2TB sn:S59CNM0RB05113H\u003e\n\u003cSAT device on /dev/sda mod:ST10000DM0004-1ZC101 sn:ZA20VNPT\u003e\n\u003cSAT device on /dev/sdb mod:ST10000DM0004-1ZC101 sn:ZA22W366\u003e\n\u003cSAT device on /dev/sdc mod:ST10000DM0004-1ZC101 sn:ZA22SPLG\u003e\n\u003cSAT device on /dev/sdd mod:ST10000DM0004-1ZC101 sn:ZA2215HL\u003e\n\u003e\n```\n\nIn general, it is recommended to run the base script with enough privileges to\nexecute smartctl, but this is not possible in all cases, so this workaround is\nprovided as a convenience. However, note that using sudo inside other\nnon-terminal projects may cause dev-bugs/issues.\n\nUsing the pySMART wrapper, Python applications be be rapidly developed to take\nadvantage of the powerful features of smartmontools.\n\nInstallation\n============\n``pySMART`` is available on PyPI and installable via ``pip``::\n\n```bash\npython -m pip install pySMART\n```\n\nThe only external (non-python) dependency is the ``smartctl`` component of the smartmontools\npackage.  This should be pre-installed in most Linux distributions, or it\ncan be obtained through your package manager.  Likely one of the following::\n\n```bash\napt-get install smartmontools\n#    or\nyum install smartmontools\n```\n\nOn Windows PC's, smartmontools must be downloaded and installed.  The latest\nversion can be obtained from the project's homepage, http://www.smartmontools.org/.\n\nNote that after installing smartmontools on Windows, the directory containing\n``smartctl.exe`` must be added to the system path, if it is not already.\n\nDocumentation\n=============\nAPI documentation for ``pySMART`` was generated using ``pdoc`` and can be\nfound in the /docs folder within the package archive.\n\nDevelopment\n===========\nTests are run using ``pytest``.  Under [folder tests](tests), there is a\nreadme with instructions on how to run the tests.\n\nAcknowledgements\n================\nI would like to thank the entire team behind smartmontools for creating and\nmaintaining such a fantastic product.\n\nIn particular I want to thank Christian Franke, who maintains the Windows port\nof the software.  For several years I have written Windows batch files that\nrely on smartctl.exe to automate evaluation and testing of large pools of\nstorage devices.  Without his work, my job would have been significantly\nmore miserable. :)\n\nAdditionally I would like to thank iXsystems, Inc., the team behind the amazing\nFreeNAS and TrueNAS products.  Several years ago that team approached me with an\ninterest in pySMART, though I have no other affiliation with the company.  At\ntheir request I made a simple change to allow pySMART to run on FreeBSD and\nchanged the license from GPL to LGPL to allow them to build upon my work and\nincorporate it into their products.  They began hosting the code on their github,\nand in the intervening years they've taken the project to all new heights.\nBecause of their work the code is now Python 3 compatible, supports NVME hardware\ndevices, and has several other improvements and bug fixes.\n\nFinal Note on Licensing\n=======================\nAt the request of several companies seeking to use this code in their products,\nthe license has been changed from GPL to the slightly more permissive LGPL.\nThis should allow you to call into pySMART as a library as use it as-is in your\nown project without fear of \"GPL contamination\".  If you are reading this and\nthinking that the license is still too restrictive, please contact me. I am very\nwilling to make the code available privately under a more permissive license,\nincluding for some corporate or commercial uses. I'd just like for you to say hello\nfirst, and tell me a bit about your project and how pySMART could fit into it. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftruenas%2Fpy-SMART","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftruenas%2Fpy-SMART","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftruenas%2Fpy-SMART/lists"}