Getting started¶
Getting started with ActivityWatch is as easy as installing, starting it, and setting up autostart (if your installation method doesn’t do it for you).
System requirements¶
The release builds are produced and tested on the following platforms. Older systems may work, but are not tested.
Windows: Windows 10 or later (x64).
macOS: macOS 12 (Monterey) or later. Releases are built with a deployment target of 12.0, so older versions fail at launch with errors such as
dyld: Library not loaded: libswift_Concurrency.dylib.Linux: a distribution with glibc 2.35 or newer (the release is built on Ubuntu 22.04, so e.g. Ubuntu 22.04+, Debian 12+, Fedora 36+). Older distributions fail with
GLIBC_2.xx not founderrors; use a newer distribution or build from source.Android: see the Play Store listing for the supported Android versions.
Installation¶
Download and run the Windows installer for the latest release on GitHub.
Download the .dmg for the latest release from GitHub and drag the .app to your Applications folder as usual. See Autostart for how to start it at login.
Starting with v0.14, there are separate downloads for Apple Silicon (arm64) and Intel (x86_64) Macs. Pick the one matching your Mac.
The latest release on GitHub is available in several formats:
.zip: unzip the archive into an appropriate directory, and run theaw-qtexecutable. See Autostart for how to start it at login..AppImage: make the file executable (chmod +x) and run it..deb(Debian, Ubuntu, and derivatives): install it with your package manager, e.g.sudo apt install ./activitywatch-<version>-linux-x86_64.deb.
Note
If you are using Arch Linux you can install using the official activitywatch-bin package in the AUR.
Install it from the Play Store, F-Droid, or using the APK from the aw-android releases page.
Note
Starting with v0.14, each release also offers an experimental Tauri distribution (files named activitywatch-tauri-*). It replaces the aw-qt tray app, embeds aw-server-rust, and on Linux bundles awatcher for native Wayland support. The classic distribution remains the default.
Usage¶
The aw-qt application is the easiest way to use ActivityWatch. It creates a trayicon and automatically starts the server and the default watchers.
If you’ve installed by extracting a zip archive, simply run the ./aw-qt binary in the installation directory (either from your terminal or on Windows by double-clicking). You now should see an icon appear in your system tray.
You should now also have the web interface running at http://localhost:5600 and within a few minutes be able to view your data in the Activity view!
If you want more advanced ways to run ActivityWatch (including running it without aw-qt), check out the “Running” section of Installing from source.
Note
If you are running GNOME or another desktop environment that does not show system tray icons, install the AppIndicator and KStatusNotifierItem Support extension to get the tray icon back. If that is not an option, or if for some reason Qt can’t be used on your machine, read Running on GNOME.
Note
If you are using a proxy ActivityWatch might not work out of the box. To fix this you can set the environment variable NO_PROXY to include 127.0.0.1 before starting aw-qt. How to set an environment variable depends on your operating system; use Google if you are unsure how to do this.
Autostart¶
Both desktop apps, aw-qt and the newer aw-tauri, have a Start at login checkbox in their tray menu. Ticking it registers ActivityWatch with your operating system so it starts when you log in; unticking it removes that registration. The change takes effect from your next login.
Note
The checkbox was added in v0.14.0. On older versions, add ActivityWatch to your system’s startup applications yourself: the Windows installer’s “Start ActivityWatch when Windows starts” option, Login Items on macOS, or your desktop environment’s startup settings on Linux (pointing at the aw-qt executable).
aw-qt |
aw-tauri |
|
|---|---|---|
Windows |
Registry value |
Registry value |
macOS |
LaunchAgent |
A Login Item for the app (macOS may ask to let ActivityWatch control “System Events”) |
Linux |
|
|
Default |
Off (except the Research Edition, which turns it on the first time it runs) |
On |
Only enable start-at-login in one of the two apps. They use the same port (5600), so if both start at login, one of them will fail to start its server (aw-tauri shows a “port already in use” error).
Note
aw-tauri stores the setting as enabled in the [autostart] section of its config.toml, and applies it every time it starts.
If you remove the login entry using your operating system’s settings instead of the checkbox, aw-tauri adds it back the next time it starts.
To turn it off for good, untick the checkbox or set enabled = false there.
If you run several instances side by side with --profile, each profile gets its own autostart entry, so the checkbox in one does not affect the others.
Existing autostart entries¶
If you set up autostart before these checkboxes existed, read the section for your system so you don’t end up with an entry you can’t turn off. A duplicate entry is harmless on its own: both apps only allow one running instance, so the second copy quits quietly.
The installers have a “Start ActivityWatch when Windows starts” option, ticked by default.
It puts a shortcut in your Startup folder (open it by typing shell:startup in the Run dialog, Win+R).
aw-qt: the checkbox recognizes the installer’s
ActivityWatchshortcut. It shows as ticked, and unticking it deletes the shortcut. The installer remembers your choice from the last install, so when you upgrade, untick the option in the installer too, otherwise it recreates the shortcut.aw-tauri: the checkbox does not know about the installer’s
ActivityWatch (Tauri)shortcut. To stop aw-tauri from starting at login, untick the checkbox and delete that shortcut from the Startup folder.
Earlier versions of these docs said to add ActivityWatch to your Login Items by hand (Apple’s guide).
aw-qt: the checkbox uses a LaunchAgent and does not see a Login Item you added by hand. Before ticking the checkbox, remove ActivityWatch from System Settings → General → Login Items. If you keep the manual Login Item instead, leave the checkbox unticked. macOS lists the LaunchAgent under “Allow in the Background” in the same settings page. If you turn it off there, it won’t start, even if the checkbox is ticked.
aw-tauri: the checkbox manages the Login Item itself and recognizes an existing
ActivityWatchLogin Item, so you don’t need to do anything.
Packages (.deb, AUR): these install a system-wide autostart entry,
/etc/xdg/autostart/aw-qt.desktop, so aw-qt starts at login even though the checkbox shows unticked. Unticking the checkbox cannot turn that entry off. To disable it, use your desktop environment’s startup settings, or override it for your user:mkdir -p ~/.config/autostart sed 's/^Hidden=.*/Hidden=true/' /etc/xdg/autostart/aw-qt.desktop > ~/.config/autostart/aw-qt.desktop
Manual entries: if you created
~/.config/autostart/aw-qt.desktopyourself (make installin aw-qt does this, and GNOME’s “Startup Applications” usually names the entry after the command), that is the same file the aw-qt checkbox manages. An entry with any other name, such as a line in your i3 or sway config, is separate: remove it if you switch to the checkbox.aw-qt AppImage: don’t use the checkbox. It currently records the temporary path the AppImage is mounted at, which is gone after a reboot. Add the
.AppImagefile to your startup applications instead. The aw-tauri AppImage is not affected.
Window managers and desktop environments that don’t support XDG Autostart ignore ~/.config/autostart.
There, start aw-qt (or aw-tauri) from wherever you keep your startup commands, or use dex to run XDG autostart entries.