Installing from source

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

Cloning the repository and submodules

Since the main ActivityWatch repository uses git submodules to manage its modules, you first need to clone the repo and then the submodules.

You can do both in one step with:

git clone --recursive

Or, if you’ve already cloned normally, you can clone the submodules using:

git submodule update --init --recursive

If you want to ensure you have the latest version of all submodules, preserving any feature branches you have:

git submodule foreach --recursive git pull

Checking dependencies

You need:

  • Git

  • Python 3.7 to 3.9, check with python3 -V (required to build the core components)

  • Poetry, check with poetry -V (can be installed like this: python3 -m pip install poetry)

  • Node 12 or higher, check with node -v and npm -v (required to build the web UI)

  • Rust nightly (nightly can be installed using rustup update), check with rustc -V and cargo -V (for building aw-server-rust)

For Windows users:

  • gnuwin32, to get the make command on Windows.

  • (optional) 7 Zip, for packaging the zip.

  • (optional) InnoSetup 6, for packaging the installer, can be installed using Chocolatey.

Commands which should work before building:

  • git --version

  • make --version

  • python --version

  • poetry --version

  • node --version / npm --version

  • rustc --version / cargo --version

  • 7z (optional)

If any of these don’t work, make sure you’ve correctly installed them and have them in your PATH variable.

Using a virtualenv

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

python3 -m venv venv

Now activate the virtualenv in your current shell session:

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

All the modules need to be installed in the same env in order to avoid build issues. This is why creating a single venv for all activitywatch repos is important and why relying on poetry to setup a per-folder venv is not an option.

The watchers all use the published versions of aw-client. If you want to use a development version of this client, you’ll need to override the definition in the pyproject.toml file via aw-client = {path = "../aw-client" }.

Building and installing

Build and install everything into the virtualenv:

make build


Now you should be able to start ActivityWatch from the terminal where you’ve activated the virtualenv.

There are two ways to run ActivityWatch:

  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

    • For the rust server, run with: aw-server-rust/target/package/aw-server-rust

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!


On Linux, if you want to run from source using a .desktop file launcher, see issue #176.

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 encounter so we can make things easier for future users.

Packaging your changes

If you made some changes and want to create a proper build with portable executables (like normal ActivityWatch releases) you need to install pyinstaller (and on Debian-like distros python3-dev).

apt install python3-dev  # Or equivalent for your Linux distribution
pip3 install --user pyinstaller

Then simply run the following to package it:

make package

When the packaging is done you will have a ./dist folder where you can find:

  • A activitywatch folder, you can move or copy that folder anywhere you need and set aw-qt to run from startup.

  • A zipped version of the folder.

  • (on Windows) An installer.