How to Install Urlwatch with pip on Ubuntu

Install Urlwatch with pip inside a Python virtual environment so the installation stays separate from Ubuntu’s system Python. Run these commands from your project directory:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade urlwatch
urlwatch --version

The final command should print the installed Urlwatch version. This is the pip installation route documented by the Urlwatch handbook, combined with the virtual environment approach recommended by the Python Packaging User Guide.

Install Urlwatch in a virtual environment

Check Python: python3 --version. Urlwatch 2.29 documents support for Python 3.8 and newer.
Create an environment: python3 -m venv .venv. This creates an isolated environment in the current directory.
Activate it: source .venv/bin/activate. The environment’s executables, including python and installed commands, are placed on your shell path.
Install or upgrade Urlwatch: python -m pip install --upgrade urlwatch.
Verify: urlwatch --version.

When the environment is active, the shell prompt often shows (.venv). Use python -m pip rather than a bare pip command: it makes clear that pip belongs to the active Python interpreter.

Keep the environment for later use

From the same project directory, reactivate it whenever you open a new shell:

source .venv/bin/activate
urlwatch --version

To leave the environment, run deactivate. The installed package remains in .venv; reactivate the environment to use it again. If you remove the directory, you remove that environment and its packages.

Why use a virtual environment on Ubuntu?

Ubuntu releases that follow PEP 668, including Ubuntu 23.04 and newer, can mark the system Python as externally managed. A system-wide pip install may then be refused to protect Python packages managed by the operating system. A project virtual environment gives pip a separate place to install Urlwatch and its dependencies.

Avoid trying to work around this by forcing pip to modify Ubuntu’s system Python. Create and activate a venv, then run the install command there. The pipx documentation describes the externally managed Python behavior and the Ubuntu pipx setup.

Requirements and optional dependencies

Urlwatch 2.29 documents Python 3.8 or newer. Its required Python packages include PyYAML, minidb, requests, keyring, platformdirs, lxml, and cssselect. Installing Urlwatch from its package distribution with pip normally installs its declared required dependencies automatically. See the Urlwatch documentation for the release’s dependency details.

Some features have optional dependencies. For example, browser-based jobs use Playwright, and certain reporters or filters need additional packages. Install optional packages only when you plan to use the feature that requires them; the core installation does not require every optional dependency.

Common installation problems

Symptom	Likely cause	Fix
`No module named venv` or an error creating the environment	The Python venv support package is missing for this Ubuntu installation.	Install the venv support package appropriate for your Ubuntu release and Python version using the release’s package manager, then retry `python3 -m venv .venv`. Package names can vary; check the installed release rather than guessing a versioned package.
`externally-managed-environment`	pip is targeting Ubuntu’s system Python rather than an isolated environment.	Run `python3 -m venv .venv`, activate it with `source .venv/bin/activate`, then run `python -m pip install --upgrade urlwatch`.
`urlwatch: command not found`	The environment is not active, or its `bin` directory is not on PATH.	From the directory containing `.venv`, run `source .venv/bin/activate`. Check that the install completed in that environment, then retry `urlwatch --version`.
Urlwatch is installed, but a different version appears	The command resolves to another installation on PATH, or the environment was not activated.	Activate the intended venv, then inspect `which urlwatch` and `python -m pip show urlwatch`. The command path should be under the intended `.venv`.
pip cannot download or resolve packages	Network access, package index access, or a Python compatibility constraint may be blocking installation.	Check network and proxy settings, confirm the Python version meets Urlwatch’s requirement, and rerun the install command. Read the full pip error to identify whether it is a connection, resolver, or compatibility failure.

Other installation options

If you specifically need pip, use the venv method above. Ubuntu also packages Urlwatch through apt, but the available version depends on the Ubuntu suite: the Jammy package index lists 2.24-1, while the Questing manpage describes 2.29-1. Check your release’s package index before choosing apt if version matters.

On Ubuntu 23.04 and newer, pipx is another application-oriented option. It installs command-line applications into isolated environments and exposes their commands on PATH. The documented setup is:

sudo apt update
sudo apt install pipx
pipx ensurepath
pipx install urlwatch

Use pipx if you prefer a managed command-line application install; use a project venv when you want the environment tied to a project or need to manage its Python packages directly. See the pipx overview.

Performance, reliability, and maintenance

Urlwatch’s installation does not require a special performance configuration. A virtual environment keeps the package set for this installation isolated from other projects, which helps avoid package version conflicts. Keep track of the directory containing .venv, since activating the wrong environment is a common reason a command appears missing.

The handbook’s command uses --upgrade, which installs the current available Urlwatch version when you run it. If you need a repeatable setup across machines, record the intended package versions in your project’s dependency management process rather than assuming every future install will resolve to the same release.

Or skip the browser setup

Urlwatch monitors page changes; if your immediate task is capturing a webpage as an image or PDF, ScreenshotNeo provides a website screenshot API. One GET request returns a PNG, JPEG, WebP, or PDF. Its capture flow can accept cookie consent and remove known consent banners, newsletter popups, and chat widgets before the shot.

For example, save a webpage screenshot with cURL:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

See the ScreenshotNeo API documentation for the request options and response behavior. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing; response headers indicate the page verdict and whether the request was billed. ScreenshotNeo also offers an MCP server so AI agents can take screenshots. Plans include 1,000 screenshots per month free with no card; paid plans start at $5 for 3,000. Learn about ScreenshotNeo or sign up for 1,000 free screenshots a month.

FAQ

Does the venv need to be named `.venv`?

No. That is a conventional directory name. Use another name if you prefer, and substitute it in the activation command.

Do I need sudo to install Urlwatch with pip?

No. The virtual environment belongs to your user and the pip install runs inside it, so the commands above do not use sudo.

Will Urlwatch start monitoring pages as soon as it is installed?

The commands here install and verify the Urlwatch CLI. They do not configure monitoring jobs; consult the Urlwatch handbook for configuration and usage instructions.