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.
Contents
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 https://github.com/ActivityWatch/activitywatch.git
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:
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
andnpm -v
(required to build the web UI)Rust nightly (nightly can be installed using
rustup update
), check withrustc -V
andcargo -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 <https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/> 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/activate.fish
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
Running¶
Now you should be able to start ActivityWatch from the terminal where you’ve activated the virtualenv.
There are two ways to run ActivityWatch:
Use the trayicon manager (Recommended for normal use)
Run from your terminal with:
aw-qt
Start each module separately (Recommended for developing)
Run from your terminal with:
aw-server
,aw-watcher-afk
, andaw-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!
Note
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 setaw-qt
to run from startup.A zipped version of the folder.
(on Windows) An installer.