This module provides a function—uptime.uptime()—that tells you how long your system has been up. This turns out to be surprisingly non-straightforward, but not impossible on any major platform. It tries to do this without creating any child processes, because parsing uptime(1)‘s output is cheating.
In the course of determining the uptime, this module may also determine the boot time. Therefore, it also provides a way to get at that: uptime.boottime().
It also exposes various platform-specific helper functions, which you probably won’t need.
You can download the latest version of this library here, or install it using easy_install or pip in the usual way.
Warning
On most platforms, this module depends very heavily on ctypes. It has become painfully apparent that many less mainstream platforms ship with a broken version of this standard library module, either accidentally or deliberately. Please test your Python installation before using uptime.
These are the platforms on which uptime has been explicitly tested, and the others on which it is therefore expected to work as well.
| Test platform | Status | Function(s) | Implications for... |
|---|---|---|---|
| Android 4.0.3 | ✓ | _uptime_linux() | Other versions of Android, hopefully |
| Cygwin 1.7.17-1 | ✓ | _uptime_linux() | |
| Debian Linux 6.0.6 | ✓ | _uptime_linux(), _uptime_posix() | Every Linux since ~1994, Cygwin |
| FreeBSD 9.1 | ✓ | _uptime_bsd() | Every BSD |
| Haiku R1 Alpha 4.1 | ✓ | _uptime_beos() | BeOS |
| Icaros Desktop 1.5.1 | ✓ | _uptime_amiga() | AROS, AmigaOS |
| Mac OS 9.0 | ✓ | _uptime_mac() | Every classic Mac |
| Mac OS X 10.7 “Lion” | ✓ | _uptime_osx(), _uptime_mac() | Every Mac OS X |
| MINIX 3.2.0 | ✓ | _uptime_minix() | |
| OpenIndiana 151a7 | ✓ | _uptime_solaris(), _uptime_posix() | Solaris and its free knock-offs |
| Plan 9 from Bell Labs, Fourth Edition | ✓ | _uptime_plan9() | |
| ReactOS 0.3.14 | ✓ | _uptime_windows() | |
| RISC OS 5.19 | ✓ | _uptime_riscos() | RISC OS in general |
| Syllable Desktop 0.6.7 | ✓ | _uptime_syllable() | AtheOS |
| Syllable Server 0.1 | ✓ | _uptime_linux() | |
| Windows 98 SE | ✓ | _uptime_windows() | Every Windows since Windows 95 |
| Windows XP SP 3 | ✓ | _uptime_windows() |
Additionally, uptime might work on Windows CE (any version), but this has not been tested. It probably won’t work on any other operating systems not listed.
>>> from uptime import uptime
>>> uptime()
49170.129999999997
Returns the uptime in seconds, or None if it can’t figure it out.
This function will try to call the right helper function for your platform (based on sys.platform), or all functions in some order until it finds one that doesn’t return None.
>>> from uptime import boottime
>>> boottime()
datetime.datetime(2013, 6, 21, 16, 22, 41)
Returns the boot time as a datetime.datetime. If it can be exactly determined, it is; otherwise, the result of uptime.uptime() is subtracted from the current time. If the uptime can’t be determined either, None is returned.
If the datetime module isn’t available, this function will raise a RuntimeError.
New in version 2.0.
Changed in version 3.0.
All of the boottime helper functions will return a datetime.datetime instance representing the boot time or None, same as uptime.boottime(). They will also raise a RuntimeError if the datetime module is unavailable. All of the uptime helper functions will return a number (probably a float) representing the uptime in seconds or None, same as uptime.uptime().
Note that if uptime.uptime() or uptime.boottime() return None for you, all of these functions will return None as well. There is probably no good reason for you to call any of them yourself, except perhaps to find out how uptime.uptime() determined the uptime. (uptime.boottime() is more difficult to diagnose, because boot time is usually figured out as a side effect of determining the uptime rather than directly through a helper function.)
They’re documented here mainly to serve as a reference for how uptime may be determined on the various platform uptime supports, which may be of use to people implementing a similar library in other languages or something.
Note that because boot time as a discrete point in time is poorly defined, platforms that are able to draw their information from multiple functions may provide slightly different numbers for each of them:
>>> import sys, uptime
>>> sys.platform
'linux2'
>>> uptime._uptime_linux() - uptime._uptime_posix()
11.416326000000481
uptime.uptime() will always call candidate helpers in the same order, so calling it twice ten seconds apart will always yield results that differ by ten seconds. If you only call uptime.uptime() and uptime.boottime(), it is also always the case that subtracting the uptime as reported by uptime.uptime() from the current time yields the boot time as reported by uptime.boottime(). This is not guaranteed if you call any of the helper functions manually, because they may cache boot time if they come across it.
A way to figure out the boot time directly on Linux. This reads the btime entry in /proc/stat, which is the boot time in seconds since the Epoch.
New in version 2.0.
AmigaOS-specific uptime. It takes the creation time of the RAM: drive to be the boot time, and subtracts it from the current time to determine the uptime.
This trick was gleaned from the uptime-DA tool created by Daniel Adolfsson, and does not require a working ctypes.
New in version 1.4.
BeOS/Haiku-specific uptime. It uses system_time() from libroot to determine the uptime.
New in version 1.2.
BSD-specific uptime (including OS X). It uses sysctl (through the sysctlbyname() function) to figure out the system’s boot time, which it then subtracts from the current time to find the uptime.
Linux-specific uptime. It first tries to read /proc/uptime, and if that fails, it calls the sysinfo() C function.
If /proc/uptime exists, this function does not require a working ctypes.
Mac OS-specific uptime. This calls GetTickCount() from the MacOS standard library module (which calls the TickCount() API function) and divides the result by 60.15 to obtain the approximate uptime in seconds.
Since TickCount() returns an unsigned 32-bit integer, this value will overflow after 826.4 days. Note that the number of ticks is only updated during vertical trace interrupts. If this interrupt is ever disabled, this function will return inaccurate results.
This function does not require a working ctypes.
Warning
The MacOS module has been removed in Python 3.x, and TickCount() has been deprecated since Mac OS X 10.8 “Mountain Lion”. OS X users should always prefer _uptime_osx() instead.
New in version 2.1.
MINIX-specific uptime. This just reads /proc/uptime.
(_uptime_linux() actually works fine on MINIX. This is a separate function because a fallback mechanism may be added in the future for versions of MINIX without procfs. MINIX’s /proc/uptime differs from Linux’s in that it only contains one number; it lacks the idle time.)
New in version 2.1.
Alias for _uptime_bsd().
Plan 9 From Bell Labs. Reads /dev/time, which contains, among other things, the number of clock ticks since boot and the number of clock ticks per second.
This function does not require a working ctypes.
Fallback uptime for POSIX. Scans the utmpx database for a BOOT_TIME entry, and if it’s present, subtracts its value from the current time to find the uptime.
Note
Because POSIX only specifies (some of) the members of struct utmpx but not their order or exact sizes, nor the values of utmpx‘s constants (and there is no way to figure these things out at runtime), this is implemented as a C extension (uptime._posix) distutils tries to compile when you install uptime. If you’re sure your utmpx database has a BOOT_TIME entry (many don’t) but you’re still getting None for an answer, it may be the case that the extension couldn’t be compiled.
New in version 1.3.
RISC OS-specific uptime. This uses the swi module to perform the software interrupt OS_ReadMonotonicTime, which returns the uptime in centiseconds. This will overflow after about eight months on 32-bit systems (2.9 billion years on 64-bit). If this can be detected, the function will return None rather than rely on assumptions regarding signed overflow.
This function does not require a working ctypes.
New in version 1.4.
Solaris-specific uptime. This uses libkstat to find out the system’s boot time (unix:0:system_misc:boot_time), which it then subtracts from the current time to find the uptime.
New in version 1.1.
Syllable-specific uptime. It assumes the mtime of the first pseudo-terminal’s master device, /dev/pty/mst/pty0, is the boot time, and subtracts that from the current time to find the uptime.
This function does not require a working ctypes.
Windows-specific uptime. From Vista onward, it will call GetTickCount64() from kernel32.lib. Before that, it calls GetTickCount(), which returns an unsigned 32-bit number representing the number of milliseconds since boot and will therefore overflow after 49.7 days. There is no way to tell when this has happened, but fortunately Windows systems won’t stay up for that long.
If you like, you can also call uptime as a script, to get a more readable replacement for the uptime that ships with your operating system (if any):
$ python -m uptime
Uptime: 109 days, 33.84 seconds.
You can also display the boot time by passing the -b switch:
$ python -m uptime -b
Booted: Wed Oct 10 06:28:24 2012 CET.
Exact output will depend on your locale and the value of the TZ environment variable.
If you’re using Python 2.6 or 3.0, you will need to call uptime.__main__ instead; see Issue 2751.
Changed in version 2.0.3: Added -b flag.