Run as a Windows service

On a lab instrument PC, run the watcher as a Windows service. This is the default setup: the service starts on boot, keeps running after you log out, restarts on failure, and participates in fleet auto-update. Foreground data-hub-watcher watch is for quick checks and non-Windows hosts.

Install the service extra

The service depends on pywin32, which ships in the windows-service extra. The default install already includes it. If you installed without it, add it now:

uv tool install "data-hub-watcher[windows-service]"

Run data-hub-watcher init first if you have not configured the watcher yet. The service uses the same ~/.data-hub/config.yaml and per-environment .env file.

Install and start

From an Administrator terminal:

data-hub-watcher service install
data-hub-watcher service start

service install registers delayed auto-start (so it does not race the network stack at boot), configures restart-on-failure recovery, and registers the DataHubWatcherUpgrade Scheduled Task used by the auto-updater.

Lifecycle commands

service reinstall is the right command after an out-of-band wheel swap (for example a manual uv tool install -U from an Administrator shell). Stop and uninstall are best-effort, so it works even if the service is already gone.

With watcher 1.4.2 and later, service stop finishes within about 25 seconds once the watcher is running, even when Data Hub doesn’t answer. It can take longer while the watcher is still starting, because it syncs its config, sends its first heartbeat and scans the watch folder before it looks for a stop. It can also take longer while the watcher applies a config change from Data Hub, which waits up to 2 minutes for uploads to finish. Once the stop begins, the watcher starts no new file or part. A part already on its way gets up to 15 seconds to arrive. In the last 10 seconds, the watcher sends its watcher_stopped event and then its final heartbeat, so it shows as Stopped when Data Hub answers.

A file that the watcher had to cut off isn’t lost. When the instrument uploads automatically, the watcher uploads that file again the next time it starts. A file that someone requested with Upload is different: service stop cancels the requests, so request the file again. A restart of the PC and the stop of an automatic update keep them queued, as When the PC restarts or shuts down describes. See also Request uploads.

service install and service reinstall accept --env-path PATH to override which .env file the service loads (defaults to ~/.data-hub/.env.<environment>).

When the PC restarts or shuts down

With watcher 1.4.1 and later, restarting the PC, or a full shutdown, stops the service the way service stop does. The watcher sends a final heartbeat, so it shows as Stopped on the Watchers page, and it records a watcher_stopped event whose message reads "Service stopped: Windows is shutting down", so you can tell a restart from a service stop. The service starts again at boot, as before. watcher.log and the Windows Application log both have the line Data Hub Watcher stopping: Windows is shutting down.

Files that someone requested with Upload stay requested across a restart, and the watcher uploads them once the service is running again. If the PC stays down and no heartbeat arrives for about 15 minutes, Data Hub cancels the requests, and you request the files again. The watcher shows Stopped until then, and Unresponsive after it. Hover over the badge on the Watchers page to see the time. Stopping the service yourself, with service stop, cancels them at once. See Request uploads.

The same goes for the stop of an automatic update (watcher 1.4.2 and later). The final heartbeat says the stop is for an update, so the watcher shows as Stopped, files someone requested with Upload stay requested, and the watcher uploads them once the service is running again on the new version. If no heartbeat arrives for about 15 minutes, Data Hub cancels the requests and the watcher shows as Unresponsive. When you update by hand with data-hub-watcher self-update, the service stops without that mark, so Data Hub cancels the requests at once, as it does for service stop.

Windows waits 10 seconds for a service to stop at a restart on Windows 10 version 1703 and later, and longer on older builds. The watcher limits its own stop to about 8 seconds either way. That is enough for the final heartbeat when Data Hub answers. A file that is still uploading is cut off, not waited for, and the watcher uploads it again after the restart. See An upload was cut off by a restart or an update.

If Data Hub can’t be reached, or the stop is cut off for another reason, the final heartbeat doesn’t arrive and the service ends with no stopped status. If the PC then stays down for more than five minutes, the watcher shows as Unresponsive until the service starts again.

Windows 10 and 11 turn on Fast Startup by default. With it, Shut down in the Start menu doesn’t stop the service: Windows saves its state and the service carries on from it at the next start, so no final heartbeat is sent and no watcher_stopped event is recorded. Restart always stops the service, and so does a shutdown with Fast Startup turned off.

Watchers older than 1.4.1 don’t ask Windows to tell them about a restart, so a restart ends them with no final heartbeat and no watcher_stopped event. Updating to 1.4.1 is enough: the service tells Windows what it handles each time it runs, so no service reinstall is needed.

Do not run watch alongside the service

Running data-hub-watcher watch interactively while the service is also running is not supported: both processes would race on the same log file and watch directory. Stop the service first if you need the CLI for debugging:

data-hub-watcher service stop
data-hub-watcher --verbose watch
data-hub-watcher service start

Where the service writes logs

The service and the CLI share one rotating log:

• C:\ProgramData\DataHubWatcher\watcher.log

A separate service-bootstrap.log next to it captures crashes before the service control dispatcher takes over (missing pywin32, moved venv, corrupt install). To turn on debug logging without a reinstall, add DATA_HUB_WATCHER_LOG_LEVEL=DEBUG to the env file the service loads and restart the service (watcher 1.4.2 and later).