Installing from source

Here’s the guide to installing ActivityWatch from source. If you are just looking to try it out, see the getting started guide instead.


This is written for Linux and macOS. For Windows the build process is more complicated and we therefore suggest using the pre-built packages instead on that operating system.

Cloning the submodules

Since the ActivityWatch bundlerepo uses submodules, you first need to clone the submodules.

This can either be done at the cloning stage with:

git clone --recursive

Or afterwards (if you’ve already cloned normally) using:

git submodule update --init --recursive

Checking dependencies

You need to ensure you have:

  • Python 3.5 or later, check with python3 -V (required to build the core components)
  • Node 5 or higher, check with node -v and npm -v (required to build the web UI)

Using a virtualenv

It is recommended to use a virtualenv in order to avoid polluting your system with ActivityWatch-specific packages Python packages. It also makes it easier to uninstall since all you have to do is remove the virtualenv folder.


If you don’t want to use a virtualenv you could instead set the environment variable PIP_USER=true when building. This will install ActivityWatch for your user only instead of trying to install it system-wide (which would fail since it requires root). If you do this, make sure that the folder ~/.local/bin (on Linux) or ~/Library/Python/<version>/bin (on macOS) is in your PATH so that you can run the programs once installed.

python3 -m venv venv

Now activate the virtualenv in your current shell session:

# For bash/zsh users:
source ./venv/bin/activate
# For fish users:
source ./venv/bin/

Building and installing

Build and install everything into the virtualenv:

make build


If you are going to develop we suggest building/installing using make build DEV=true which installs all Python packages with pip’s handy --editable flag. By doing this you wont have to reinstall everything whenever you want to try out a code change.


Now you should be able to start ActivityWatch from the terminal where you’ve activated the virtualenv. Or, if you were using the PIP_USER trick, from any terminal with a correctly configured PATH. You have two options:

  1. Use the trayicon manager (Recommended for normal use)
    • Run from your terminal with: aw-qt
  2. Start each module separately (Recommended for developing)
    • Run from your terminal with: aw-server, aw-watcher-afk, and aw-watcher-window

Both methods take the --testing flag as a command line parameter to run in testing mode. This runs the server on a different port (5666) and uses a separate database file to avoid mixing your important data with your testing data.

Now everything should be running! Check out the web UI at http://localhost:5600/

If anything doesn’t work, let us know!

Updating from source

First pull the latest version of the repo with git pull then get the updated submodules with git submodule update --init --recursive. All that’s needed then is a make build.

If it doesn’t work, you can first try to run make uninstall and then do a fresh make build. If that fails as well, remove the virtualenv and start over.

Please report all issues you might have so we can make things easier for future users.