Installation Troubleshooting

Common installation and upgrade issues on Debian/Ubuntu systems, including WSL, and how to resolve them.

“externally-managed-environment” error

If you see this when running pip install obsidianwall-verdict:

error: externally-managed-environment
× This environment is externally managed

This is expected behavior on modern Debian/Ubuntu systems (Ubuntu 23.04+, Debian 12+, and WSL distributions based on them) — not an error specific to Verdict. Since PEP 668, these systems block pip from installing directly into the system Python to prevent conflicts with OS-managed packages. Every Python package hits this identical error on these systems, not just Verdict.

Recommended: install with pipx

pipx installs CLI tools like Verdict into their own isolated environment automatically:

sudo apt install pipx
pipx ensurepath
pipx install obsidianwall-verdict

Restart your terminal after pipx ensurepath so verdict is available on your PATH.

Upgrading later:

pipx upgrade obsidianwall-verdict

Alternative: use a virtual environment

python3 -m venv ~/.venvs/obsidianwall
source ~/.venvs/obsidianwall/bin/activate
pip install --upgrade obsidianwall-verdict

You’ll need to run the source command in any new terminal session before using verdict.

Not recommended, but available

pip install --upgrade obsidianwall-verdict --break-system-packages

This bypasses the safety check Debian/Ubuntu put in place to prevent conflicts with system-managed packages. Prefer pipx or a virtual environment instead.

“verdict –version” shows an old version after upgrading

If pipx upgrade obsidianwall-verdict reports success but verdict --version still shows an outdated version, you likely have two separate verdict installations on your system — an old one (from a previous pip install, a manual install, or an earlier pipx install that predates a PATH change) that your shell finds before pipx’s managed version.

Check which file is actually running:

which verdict

If this does not point to a path containing .local/share/pipx/venvs/obsidianwall-verdict, that’s the conflict.

Fix:

# Remove the old conflicting file — path will match what
# `which verdict` showed you above
rm ~/.local/bin/verdict

# Reinstall cleanly through pipx
pipx reinstall obsidianwall-verdict

# Confirm
verdict --version

Installation Guide → · Quickstart →