nvchecker(1)

📦

version 2.22 · 7 versions

✨ Name ✨

okay so welcome to nvchecker(1) from the General Commands Manual — this is the manual page for nvchecker, aka New version checker for software releases. periodt 💅

nvchecker (short for new version checker) is for checking if a new version of some software has been released. main character energy for release-watching 👑

This is the version 2.0 branch. For the old version 1.x, please switch to the v1.x branch. Also chillin’ in the header are these URLs: https://github.com/lilydjwg/nvchecker/actions?query=workflow%3A%22run+tests%22 and https://badge.fury.io/py/nvchecker.

🌸 Dependency 🌸

okay bestie, here’s the dependency checklist — no cap, check every line:

Python 3.9+
Python library: structlog, platformdirs, tomli (on Python < 3.11)
One of these Python library combinations (ordered by preference):
- tornado + pycurl
- aiohttp
- httpx with http2 support (experimental; only latest version is supported)
- tornado
All commands used in your software version configuration files

🎀 Install and Run 🎀

To install, run this and let it cook:

pip3 install nvchecker

To use the latest code, you can also clone this repository and run:

python3 setup.py install

To see available options:

nvchecker --help

Run with one or more software version files:

nvchecker -c config_file.toml

A simple config file may look like:

[nvchecker]
source = "github"
github = "lilydjwg/nvchecker"

[python-toml]
source = "pypi"
pypi = "toml"

You normally will like to specify some "version record files"; see below. iykyk 🫶

📜 JSON logging 📜

With --logger=json or --logger=both, you can get a structured logging setup for programmatically consuming. You can use --json-log-fd=FD to specify the file descriptor to send logs to (take care to do line buffering). The logging level option (-l or --logging) doesn't take effect with this.

The JSON log is one JSON string per line. The following documented events and fields are stable, undocumented ones may change without notice.

event=updated — An update is detected. Fields name, revision, old_version and version are available. old_version may be null and revision may be absent.
event=up-to-date — There is no update. Fields name and version are available.
event=no-result — No version is detected. There may be an error. Field name is available.
level=error — There is an error. Fields name and exc_info may be available to give further information.

💥 Upgrade from 1.x version 💥

There are several backward-incompatible changes from the previous 1.x version. bestie, read these before you rawdog an upgrade 😭

Version 2.x requires Python 3.7+ to run.
The command syntax changes a bit. You need to use a -c switch to specify your software version configuration file (or use the default).
The configuration file format has been changed from ini to toml https://toml.io/. You can use the nvchecker-ini2toml script to convert your old configuration files. However, comments and formatting will be lost, and some options may not be converted correctly.
Several options have been renamed. max_concurrent to max_concurrency, and all option names have their - be replaced with _.
All software configuration tables need a source option to specify which source is to be used rather than being figured out from option names in use. This enables additional source plugins to be discovered.
The version record files have been changed to use JSON format (the old format will be converted on writing).
The vcs source is removed. (It's available inside lilac https://github.com/archlinuxcn/lilac at the moment.) A git source is provided.
include_tags_pattern and ignored_tags are removed. Use List Options instead.

🗂️ Version Record Files 🗂️

Version record files record which version of the software you know or is available. They are a simple JSON object mapping software names to known versions. literally just name-to-version vibes ✨

🫶 The `nvtake` Command 🫶

This command helps to manage version record files. It reads both old and new version record files, and a list of names given on the commandline. It then updates the versions of those names in the old version record file.

This helps when you have known (and processed) some of the updated software, but not all. You can tell nvchecker that via this command instead of editing the file by hand. slay, no manual JSON wrangling 💚

This command will help most if you specify where your version record files are in your config file. See below for how to use a config file.

🧚 The `nvcmp` Command 🧚

This command compares the newver file with the oldver one and prints out any differences as updates, e.g.:

$ nvcmp -c sample_source.toml
Sparkle Test App None -> 2.0
test 0.0 -> 0.1

🌈 Configuration Files 🌈

The software version source files are in toml https://toml.io/ format. The key name is the name of the software. Following fields are used to tell nvchecker how to determine the current version of that software.

See sample_source.toml https://github.com/lilydjwg/nvchecker/blob/master/sample_config.toml for an example. yes, literally that file name and that URL, bestie 🍋

⚙️ Configuration Table ⚙️

A special table named __config__ provides some configuration options.

Relative paths are relative to the source files, and ~ and environmental variables are expanded.

Currently supported options are:

oldver — Specify a version record file containing the old version info.
newver — Specify a version record file to store the new version info.
proxy — The HTTP proxy to use. The format is proto://host:port, e.g. http://localhost:8087. Different backends have different level support for this, e.g. with pycurl you can use socks5h://host:port proxies.
max_concurrency — Max number of concurrent jobs. Default: 20.
http_timeout — Time in seconds to wait for HTTP requests. Default: 20.
keyfile — Specify a toml config file containing key (token) information. This file should contain a keys table, mapping key names to key values. See specific source for the key name(s) to use.

Sample keyfile.toml:

[keys]
# https://github.com/settings/tokens
# scope: repo -> public_repo
github = "ghp_<stripped>"

👑 Global Options 👑

The following options apply to every check source. You can use them in any item in your configuration file. global tea, apply everywhere 💜

prefix — Strip the prefix string if the version string starts with it. Otherwise the version string is returned as-is.

If both prefix and from_pattern/to_pattern are used, prefix is applied first.

from_pattern, to_pattern — Both are Python-compatible regular expressions. If from_pattern is found in the version string, it will be replaced with to_pattern.

If from_pattern is not found, the version string remains unchanged and no error is emitted.

missing_ok — Suppress warnings and errors if a version checking module finds nothing. Not all sources support it.
proxy — The HTTP proxy to use. The format is proto://host:port, e.g. http://localhost:8087. Different backends have different level support for this, e.g. with pycurl you can use socks5h://host:port proxies.

Set it to "" (empty string) to override the global setting.

This only works when the source implementation uses the builtin HTTP client, and doesn't work with the aur source because it's batched (however the global proxy config still applies).

user_agent — The user agent string to use for HTTP requests.
tries — Try specified times when a network error occurs. Default is 1.

This only works when the source implementation uses the builtin HTTP client.

httptoken — A personal authorization token used to fetch the url with the Authorization header. The type of token depends on the authorization required.
- For Bearer token set : Bearer <Your_bearer_token>
- For Basic token set : Basic <Your_base64_encoded_token>

In the keyfile add httptoken_{name} token.

verify_cert — Whether to verify the HTTPS certificate or not. Default is true.

🍓 List Options 🍓

The following options apply to sources that return a list. See individual source tables to determine whether they are supported. list-source besties, this is your section 🍓

include_regex — Only consider version strings that match the given regex. The whole string should match the regex. Be sure to use .* when you mean it!
exclude_regex — Don't consider version strings that match the given regex. The whole string should match the regex. Be sure to use .* when you mean it! This option has higher precedence that include_regex; that is, if matched by this one, it's excluded even it's also matched by include_regex.
sort_version_key — Sort the version string using this key function. Choose among parse_version, vercmp, awesomeversion and portage. Default value is parse_version. parse_version uses an old version of pkg_resources.parse_version. vercmp uses pyalpm.vercmp. awesomeversion uses awesomeversion https://github.com/ludeeus/awesomeversion. portage uses portage.versions.vercmp.
ignored — Version strings that are explicitly ignored, separated by whitespace. This can be useful to avoid some known mis-named versions, so newer ones won't be "overridden" by the old broken ones.

🔎 Search in a Webpage 🔎

source = "regex"

Search through a specific webpage for the version string. This type of version finding has these fields:

url — The URL of the webpage to fetch.
encoding — (Optional) The character encoding of the webpage, if latin1 is not appropriate.
regex — A regular expression used to find the version string.

It can have zero or one capture group. The capture group or the whole match is the version string.

When multiple version strings are found, the maximum of those is chosen.

post_data — (Optional) When present, a POST request (instead of a GET) will be used. The value should be a string containing the full body of the request. The encoding of the string can be specified using the post_data_type option.
post_data_type — (Optional) Specifies the Content-Type of the request body (post_data). By default, this is application/x-www-form-urlencoded.

This source supports List Options.

🦋 Search in an HTTP header 🦋

source = "httpheader"

Send an HTTP request and search through a specific header.

url — The URL of the HTTP request.
header — (Optional) The header to look at. Default is Location. Another useful header is Content-Disposition.

The regex source is literally right here, no cap:

regex — the regular expression used to find the version string. It can have zero or one capture group. The capture group or the whole match is the version string. When multiple version strings are found, the maximum of those is chosen. 💅
method (Optional) — the HTTP method to use. Default is HEAD.
follow_redirects (Optional) — whether to follow 3xx HTTP redirects. Default is false. If you are looking at a Location header, you shouldn't change this.

🔎 Search with an HTML Parser

source = "htmlparser"

Send an HTTP request and search through the body a specific xpath. It's giving "find the version in the HTML" energy ✨

url — the URL of the HTTP request.
xpath — an xpath expression used to find the version string.
is_xml — set to true to use an XML parser instead of an HTML one.
post_data (Optional) — when present, a POST request (instead of a GET) will be used. The value should be a string containing the full body of the request. The encoding of the string can be specified using the post_data_type option.
post_data_type (Optional) — specifies the Content-Type of the request body (post_data). By default, this is application/x-www-form-urlencoded.

This source can parse an RSS feed like this:

[ProxmoxVE]
source = "htmlparser"
url = "https://my.proxmox.com/en/announcements/tag/proxmox-ve/rss"
xpath = "//item/title"
is_xml = true
from_pattern = 'Proxmox VE ([\d.]+) released!'
to_pattern = '\1'

Note: an additional dependency "lxml" is required. You can use pip install 'nvchecker[htmlparser]'.

🧃 Search with an JSON Parser (jq)

source = "jq"

Send an HTTP request and search through the body with a specific jq filter. JSON girlies stay winning 🫶

url — the URL of the HTTP request.
filter — an jq filter used to find the version string.
post_data (Optional) — when present, a POST request (instead of a GET) will be used. The value should be a string containing the full body of the request. The encoding of the string can be specified using the post_data_type option.
post_data_type (Optional) — specifies the Content-Type of the request body (post_data). By default, this is application/json.

This source supports List Options.

Note: an additional dependency "jq" is required.

🐚 Find with a Command

source = "cmd"

Use a shell command line to get the version. The output is striped first (yes, that's the word in the manpage 😭), so trailing newlines do not bother.

cmd — the command line to use. This will run with the system's standard shell (i.e. /bin/sh).

📦 Check AUR

source = "aur"

Check Arch User Repository (https://aur.archlinux.org/) for updates. Per-item proxy setting doesn't work for this because several items will be batched into one request. Batching is iconic until it ruins your proxy vibe 💀

aur — the package name in AUR. If empty, use the name of software (the table name).
strip_release — strip the release part.
use_last_modified — append last modified time to the version.

🐙 Check GitHub

source = "github"

Check GitHub (https://github.com/) for updates. The version returned is in date format %Y%m%d.%H%M%S, e.g. 20130701.012212, unless use_latest_release, use_max_tag or use_max_release is used. See below. 👑

github — the github repository, with author, e.g. lilydjwg/nvchecker.
branch — which branch to track? Default: the repository's default.
path — only commits containing this file path will be returned.
host — hostname for self-hosted GitHub instance.
use_latest_release — set this to true to check for the latest release on GitHub.

GitHub releases are not the same as git tags. You'll see big version names and descriptions in the release page for such releases, e.g. zfsonlinux/zfs's releases (https://github.com/zfsonlinux/zfs/releases), and those small ones like nvchecker's (https://github.com/lilydjwg/nvchecker/releases) are only git tags that should use use_max_tag below.

Will return the release's tag name instead of date. (For historical reasons it doesn't return the release name. See below to change.)

use_max_release — set this to true to check for the max release on GitHub. This option returns the largest one sorted by the sort_version_key option. Will return the tag name instead of date.
use_release_name — when use_latest_release or use_max_release is true, setting this to true will cause nvchecker to return the release name instead of the tag name.
include_prereleases — when use_latest_release or use_max_release is true, set this to true to take prereleases into account.

This returns the release names (not the tag names).

This requires a token because it's using the v4 GraphQL API.

use_latest_tag — set this to true to check for the latest tag on GitHub.

This requires a token because it's using the v4 GraphQL API.

query — when use_latest_tag is true, this sets a query for the tag. The exact matching method is not documented by GitHub.
use_max_tag — set this to true to check for the max tag on GitHub. Unlike use_max_release, this option includes both annotated tags and lightweight ones, and return the largest one sorted by the sort_version_key option. Will return the tag name instead of date.
token — a personal authorization token used to call the API.

An authorization token may be needed in order to use use_latest_tag, include_prereleases or to request more frequently than anonymously.

To set an authorization token, you can set:

the token option
an entry in the keyfile for the host (e.g. github.com)
an entry in your netrc file for the host

This source supports List Options when use_max_tag or use_max_release is set.

🌈 RichResult metadata

When available from the existing GitHub API responses, this source populates the following optional RichResult fields. No additional API requests are issued solely to retrieve timestamp information.

Here's the field tea, table-style but as a list because we're cute like that:

default commit/path — creation_time: •; revision_creation_time: commit timestamp
use_latest_release — creation_time: release publish time; revision_creation_time: •
use_max_release — creation_time: release publish time; revision_creation_time: •
use_latest_release + include_prereleases — creation_time: release publish time; revision_creation_time: commit timestamp
use_latest_tag — creation_time: •; revision_creation_time: tag creation time (annotated tags) or commit timestamp (lightweight tags)
use_max_tag — creation_time: •; revision_creation_time: •

🍵 Check Gitea

source = "gitea"

Check Gitea (https://gitea.com/) for updates. The version returned is in date format %Y%m%d, e.g. 20130701, unless use_max_tag is used. See below. 🌸

gitea — the gitea repository, with author, e.g. gitea/tea.
branch — which branch to track? Default: the repository's default.
use_max_tag — set this to true to check for the max tag on Gitea. Will return the biggest one sorted by old pkg_resources.parse_version. Will return the tag name instead of date.
use_latest_release — set this to true to check for the latest release name on gitea.

Gitea releases are not the same as git tags. You'll see big version names and descriptions in the release page for such releases, e.g. ciberandy/qiv's releases (https://codeberg.org/ciberandy/qiv/releases).

host — hostname for self-hosted Gitea instance.
token — Gitea authorization token used to call the API.

To set an authorization token, you can set:

the token option
an entry in the keyfile for the host (e.g. gitea.com)
an entry in your netrc file for the host

This source supports List Options when use_max_tag is set.

🦋 Check Gogs / Forgejo / Codeberg

Please use the above "gitea" source. Gitea is a fork of Gogs (https://gogs.io/). Forgejo (https://forgejo.org/) is a fork of Gitea. Codeberg is a code hosting provider that uses Forgejo. They share the same API endpoints nvchecker uses.

Alternatively, you can try the generic "git" source.

🪣 Check BitBucket

source = "bitbucket"

💻 Check BitBucket

source = "bitbucket"

Peek at BitBucket (bitbucket.org) for updates. The version it hands back is in date format %Y%m%d, like 20130701, unless use_max_tag is on. Details below, bestie 🫶

bitbucket — the bitbucket repository, with author, e.g. lilydjwg/dotvim.
branch — which branch are we tracking? Default: the repository's default.
use_max_tag — set this to true to check for the max tag on BitBucket. Returns the biggest one sorted by the old pkg_resources.parse_version. Returns the tag name instead of the date.
use_sorted_tags — if true, tags are queried and sorted according to the query and sort keys. Returns the tag name instead of the date.
query — a query string used to filter tags when use_sorted_tags is set (examples over at https://developer.atlassian.com/cloud/bitbucket/rest/intro/#querying). Ngl the string does not need to be escaped ✨
sort — a field used to sort the tags when use_sorted_tags is set (examples at https://developer.atlassian.com/cloud/bitbucket/rest/intro/#filtering). Defaults to -target.date, which sorts tags in descending order by date.
max_page — how many pages do we search for the max tag? Default is 3. This works when use_max_tag is set.

This source supports List Options when use_max_tag or use_sorted_tags is set 🔥

🦊 Check GitLab

source = "gitlab"

Peek at GitLab (gitlab.com) for updates. The version returned is in date format %Y%m%d, e.g. 20130701, unless use_max_tag is used. See below 💖

gitlab — the gitlab repository, with author, e.g. Deepin/deepin-music.
branch — which branch to track?
use_max_tag — set this to true to check for the max tag on GitLab. Returns the biggest one sorted by the old pkg_resources.parse_version. Returns the tag name instead of the date.
host — hostname for a self-hosted GitLab instance.
token — GitLab authorization token used to call the API.

To set an authorization token, you can set:

the token option
an entry in the keyfile for the host (e.g. gitlab.com)
an entry in your netrc file for the host

This source supports List Options when use_max_tag is set ✨

🎀 RichResult metadata

When it's available from the existing GitLab API responses, this source populates the following optional RichResult fields. No additional API requests are issued solely to retrieve timestamp information 🙈

Mode default commit — creation_time: (not set) · revision_creation_time: commit timestamp
Mode use_max_tag — creation_time: tag creation time · revision_creation_time: commit timestamp

🐍 Check PyPI

source = "pypi"

Peek at PyPI (pypi.python.org) for updates. Yanked releases are ignored, periodt 💅

pypi — the name used on PyPI, e.g. PySide.
use_pre_release — whether to accept pre release. Default is false.

This source supports List Options 🌸

RichResult metadata:

Mode all versions — creation_time: earliest available file upload time · revision_creation_time: (not set)

📌 Note: an additional dependency packaging is required. You can use pip install 'nvchecker[pypi]'.

💎 Check RubyGems

source = "gems"

Peek at RubyGems (rubygems.org) for updates.

gems — the name used on RubyGems, e.g. sass.

This source supports List Options ⭐

📦 Check NPM Registry

source = "npm"

Peek at the NPM Registry (registry.npmjs.org) for updates.

npm — the name used on NPM Registry, e.g. coffee-script.

To configure which registry to query, a source plugin option is available. You can specify it like this:

[__config__.source.npm]
registry = "https://registry.npm.taobao.org"

🍓 Check Hackage

source = "hackage"

Peek at Hackage (hackage.haskell.org) for updates.

hackage — the name used on Hackage, e.g. pandoc.

☕ Check Maven

source = "maven"

Peek at a Maven repository (maven.apache.org) for updates.

repo — URL of the repository to check (defaults to https://repo1.maven.org/maven2).
group — group identifier for the coordinates.
artifact — artifact identifier for the coordinates.

🐪 Check CPAN

source = "cpan"

Peek at MetaCPAN (metacpan.org) for updates.

cpan — the name used on CPAN, e.g. YAML.

📊 Check CRAN

source = "cran"

Peek at CRAN (cran.r-project.org/web/packages/) for updates.

cran — the name used on CRAN, e.g. xml2.

🎼 Check Packagist

source = "packagist"

Peek at Packagist (packagist.org) for updates.

packagist — the name used on Packagist, e.g. monolog/monolog.

🦀 Check crates.io

source = "cratesio"

Peek at crates.io (crates.io) for updates. Yanked releases are ignored, no cap 💀

cratesio — the crate name on crates.io, e.g. tokio.
use_pre_release — whether to accept pre release. Default is false.

This source supports List Options 🦋

🏹 Check Local Pacman Database

source = "pacman"

This one's for when you run nvchecker on an Arch Linux system and the program always keeps up with a package in your configured repositories for Pacman (wiki.archlinux.org/title/Pacman).

pacman — the package name to reference to.
strip_release — strip the release part.

🏛️ Check Arch Linux official packages

source = "archpkg"

This lets you track the update of Arch Linux official packages (www.archlinux.org/packages/), without needing pacman and an updated local Pacman databases. Iconic honestly 👑

archpkg — name of the Arch Linux package.
strip_release — strip the release part, only return the part before -.
provided — instead of the package version, return the version this package provides. Its value is what the package provides, and strip_release takes effect too. This is best used with libraries.

🌀 Check Debian Linux official packages

source = "debianpkg"

This lets you track the update of Debian Linux official packages (packages.debian.org), without needing apt and an updated local APT database. Slay 🫶

debianpkg — name of the Debian Linux source package.
suite — name of the Debian release (jessie, wheezy, etc, defaults to sid)
strip_release — strip the release part.

🧡 Check Ubuntu Linux official packages

source = "ubuntupkg"

This lets you track the update of Ubuntu Linux official packages (packages.ubuntu.com), without needing apt and an updated local APT database.

ubuntupkg — name of the Ubuntu Linux source package.
suite — name of the Ubuntu release (xenial, zesty, etc, defaults to None, which means no limit on suite)
strip_release — strip the release part.

🔍 Check Repology

source = "repology"

This lets you track updates from Repology (repology.org).

repology — name of the project to check.
repo — check the version in this repo. This field is required.
subrepo — check the version in this subrepo. This field is optional. When omitted, all subrepos are queried.

This source supports List Options ✨

🧚 Check Anitya

source = "anitya"

This lets you track updates from Anitya (release-monitoring.org).

anitya — distro/package, where distro can be a lot of things like "fedora", "arch linux", "gentoo", etc. package is the package name of the chosen distribution.
anitya_id — the identifier of the project/package in anitya.

💡 Note that either anitya or anitya_id needs to be specified, and anitya_id is preferred when both are specified.

🤖 Check Android SDK

source = "android_sdk"

This lets you track updates of Android SDK packages listed in sdkmanager --list.

android_sdk — the package path prefix. This value is matched against the path attribute in all <remotePackage> nodes in an SDK manifest XML. The first match is used for version comparisons.
repo — should be one of addon or package. Packages in addon2-1.xml use addon and packages in repository2-1.xml use package.
channel — choose the target channel from one of stable, beta, dev or canary. This option also accepts a comma-separated list to pick from multiple channels. For example, the latest unstable version is picked with beta,dev,canary. The default is stable.
host_os — choose the target OS for the tracked package from one of linux, macosx, windows. The default is linux. For OS-independent packages (e.g., Java JARs), this field is ignored.

This source supports List Options 🌈

✨ Check Sparkle framework

source = "sparkle"

This lets you track updates of macOS applications which use the Sparkle framework (sparkle-project.org). Obsessed 🎀

sparkle — the url of the sparkle appcast.
release_notes_language — the language of release notes to return when localized release notes are available (defaults to en for English; the unlocalized release notes are used as a fallback)

🐙 Check Pagure

source = "pagure"

This lets you check updates from Pagure (pagure.io).

pagure — the project name, optionally with a namespace.
host — the hostname of the alternative instance, like src.fedoraproject.org. 🫶

This source returns tags and supports List Options, bestie. ✨

💅 Check APT repository

source = "apt"

This one lets you track updates from literally any APT repository out there — no apt needed, no fresh local APT database needed. It's giving self-sufficient queen. 👑

pkg — name of the APT binary package.
srcpkg — name of the APT source package.
mirror — URL of the repository.
suite — name of the APT repository release (jessie, wheezy, etc.)
repo — name of the APT repository (main, contrib, etc, defaults to main)
arch — architecture of the repository (i386, amd64, etc, defaults to amd64)
strip_release — strip the release part.

Heads up bestie: either pkg or srcpkg needs to be specified (but not both), otherwise the item name gets used as pkg. No cap. 🙈

🍓 Check RPM repository

source = "rpmrepo"

This one checks the latest package versions in an arbitrary RPM repository in repomd format — the kind used by package managers like dnf (Fedora, RHEL, AlmaLinux etc.) or zypper (openSUSE) — and you don't need any native RPM tools for it. Iconic behaviour honestly. 💅

pkg — name of the RPM package (you can also use rpmrepo like with other sources, but pkg is preferred for clarity 👑)
repo — URL of the repository (required, repodata/repomd.xml should be there)
arch — architecture of the RPM package (binary, src, any, x86_64, aarch64, etc, defaults to binary)

This source supports List Options. ✨

Note: the additional dependency lxml is required. On Python versions earlier than 3.14, zstandard is required as well. You can install them with pip install 'nvchecker[rpmrepo]'. 🎀

🦋 Check Git repository

source = "git"

This lets you check tags or branch commits of an arbitrary git repository — also super useful for situations like a github project having way too many tags. 😭

git — URL of the Git repository.
use_commit — return a commit hash instead of tags.
branch — when use_commit is true, return the commit on the specified branch instead of the default one.

When this source returns tags (i.e. use_commit is not true) it supports List Options. 🌸

🧚 Check Git repository without git CLI using pygit2

source = "git_pygit2"

Basically the git source's cousin — same vibe, but it uses pygit2/libgit2 instead of invoking the git executable. Perfect for environments where Python packages can be installed but external binaries cannot be executed. Main character energy for sandboxed setups. 🔥

git — URL of the Git repository.
username — username to use for HTTP authentication.
password_key — key name used to retrieve the password or access token from the configured keyfile.
use_commit — return a commit hash instead of tags.
branch — when use_commit is true, return the commit on the specified branch instead of the default one.

Example for a private GitHub repository:

source = "git_pygit2"
git = "https://github.com/example/private-repo.git"
username = "x-access-token"
password_key = "github"

When this source returns tags (use_commit is not true) it supports List Options. ⭐

Note: an additional dependency pygit2 is required. 🫶

🌈 Check Git repository without git CLI using Dulwich

💀 okay so real talk — the original page literally has a formatting oopsie here. The heading underline is too short, and the build coughs up this warning right in the middle of the text. I'm keeping it verbatim because I refuse to lie to you: System Message: WARNING/2 (usage.rst:, line 1040) Title underline too short. Check Git repository without git CLI using Dulwich ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

source = "git_dulwich"

This is similar to the git source, but it uses Dulwich instead of invoking the git executable. Again: useful in environments where Python packages can be installed but external binaries cannot be executed. 🎀

This source does not support proxy environment variables currently. Slight L, but we move. 😭

git — URL of the Git repository.
username — username to use for HTTP authentication.
password_key — key name used to retrieve the password or access token from the configured keyfile.
use_commit — return a commit hash instead of tags.
branch — when use_commit is true, return the commit on the specified branch instead of the default one.

Example for a private GitHub repository:

source = "git_dulwich"
git = "https://github.com/example/private-repo.git"
username = "x-access-token"
password_key = "github"

When this source returns tags (use_commit is not true) it supports List Options. 💜

Note: an additional dependency dulwich is required. 🦋

💖 Check Mercurial repository

source = "mercurial"

This enables you to check tags of an arbitrary mercurial (hg) repository. Old school but still slaying. 👑

mercurial — URL of the Mercurial repository.

This source returns tags and supports List Options. ✨

🐳 Check container registry

source = "container"

This lets you check tags of images on a container registry like Docker. Obsessed honestly. 🎀

container — the path (and tag) for the container image. For official Docker images, use namespace library/ (e.g. library/python).

If no tag is given, it checks the latest available tag (sort by tag name), otherwise, it checks the tag's update time. ⏰

registry — the container registry host. Default: docker.io

registry and container are the host and the path used in the pull command. Note that the docker command allows omitting some parts of the container name while this plugin requires the full name. If the host part is omitted, use docker.io, and if there is no slash in the path, prepend library/ to the path. Here are some examples, bestie — I turned the big table into a list so it doesn't explode in your terminal: 💅

docker pull quay.io/prometheus/node-exporter → registry = quay.io, container = prometheus/node-exporter
docker pull quay.io/prometheus/node-exporter:master → registry = quay.io, container = prometheus/node-exporter:master
docker pull openeuler/openeuler → registry = docker.io, container = openeuler/openeuler
docker pull openeuler/openeuler:20.03-lts → registry = docker.io, container = openeuler/openeuler:20.03-lts
docker pull python → registry = docker.io, container = library/python
docker pull python:3.11 → registry = docker.io, container = library/python:3.11

└─────────────────────────────────────────┴───────────┴─────────────────────────────────┘

If no tag is given, this source returns tags and supports List Options. 💅

✨ Check ALPM database ✨

source = "alpm"

Okay bestie, this one checks for package updates in a local ALPM database. Very Arch of you. 🫶

alpm — the name of the package.
repo — the name of the package repository the package lives in. If you don't give it, nvchecker will use the repos value instead, see right below.
repos — an array of possible repositories the package might be chillin' in, and nvchecker will use the first repository that actually contains the package. If you don't provide it, core, extra and multilib get used, in that order. default behavior, iconic.
dbpath — path to the ALPM database directory. Default is /var/lib/pacman. Heads up though: you need to update the database yourself. nvchecker is not your personal pacman, bestie.
strip_release — strips the release part, so it only returns the part before -.
provided — instead of the package version, returns the version this package provides. Its value is what the package provides, and strip_release takes effect here too. Best used with libraries. 🧚

Note: an additional dependency pyalpm is required. No cap, you gotta install it. 😭

✨ Check ALPM files database ✨

source = "alpmfiles"

This searches package files in a local ALPM files database, and the package does not need to be installed. Lowkey so useful for checking shared library versions when a package doesn't list them in its provides. 🌸

pkgname — name of the package.
filename — regular expression for the file path. If it contains one matching group, that group is returned. Otherwise the whole file path gets returned. Paths do not have an initial slash, jsyk. For example, usr/lib/libuv\.so\.([^.]+) matches the major shared library version of libuv. 🔥
repo — name of the package repository the package resides in. If you don't provide it, it searches all repositories.
strip_dir — strips the directory from the path before matching. Defaults to false.
dbpath — path to the ALPM database directory. Default: /var/lib/pacman. And again: you need to update the database yourself, with pacman -Fy.

This source runs the pacman -Flq ... command. Wanna configure how many pacman instances run concurrently? Say less:

[__config__.source.alpmfiles]
concurrency = 2

By default it's 2. And listen — pacman -Flq ... uses a lot of memory, so be careful. Like, genuinely careful. 💀

✨ Check Open Vsx ✨

source = "openvsx"

Checks https://open-vsx.org/ for updates. 👑

openvsx — the extension's Unique Identifier on open-vsx.org, e.g. ritwickdey.LiveServer.

✨ Check Visual Studio Code Marketplace ✨

source = "vsmarketplace"

Checks https://marketplace.visualstudio.com/vscode/ for updates. 🦋

vsmarketplace — the extension's Unique Identifier on marketplace.visualstudio.com/vscode, e.g. ritwickdey.LiveServer.

✨ Check Go packages and modules ✨

source = "go"

Checks https://pkg.go.dev/ for updates. Go off. 🏃‍♀️💨

go — the name of the Go package or module, e.g. github.com/caddyserver/caddy/v2/cmd.

✨ Check opam repository ✨

source = "opam"

This one lets you check the latest package versions in an arbitrary opam repository (https://opam.ocaml.org/doc/Manual.html#Repositories) without needing the opam command line tool. Obsessed with the convenience honestly. 💜

pkg — name of the opam package.
repo — URL of the repository (optional, the default https://opam.ocaml.org repository is used if you don't specify one).

This source supports List Options. ✨

✨ Check Snapcraft ✨

source = "snapcraft"

This source lets you check the latest package versions in the Snapcraft (https://snapcraft.io). 🍓

snap — name of the snap package.
channel — name of the channel.

✨ Combine others' results ✨

source = "combiner"

This source can combine results from other entries. Main character energy: it doesn't fetch anything itself, it just vibes off everyone else. 🌈

from — a list of entry names to wait results for.
format — a format string to combine the results into the final string.

Example, because examples ate:

[entry-1]
source = "cmd"
cmd = "echo 1"

[entry-2]
source = "cmd"
cmd = "echo 2"

[entry-3]
source = "combiner"
from = ["entry-1", "entry-2"]
format = "$1-$2"

✨ Manually updating ✨

source = "manual"

This lets you manually specify the version — maybe because you wanna approve each release before it gets to the script. Very "I'm the boss here" of you. 👑

manual — the version string.

✨ Extending ✨

It's possible to extend the supported sources by writing plugins. See plugin for documentation. Go build something, bestie, I believe in you. 🎀

okay that's the whole page, you made it to the end, I'm so proud 🫶 this was nvchecker(1), version 2.22, dated 2026-08-15 — now go check some versions, slay, periodt. 💖✨

📦 where this page comes from

arch rolling: nvchecker 2.22-1 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms

nvchecker(1)

✨ Name ✨

🌸 Dependency 🌸

🎀 Install and Run 🎀

📜 JSON logging 📜

💥 Upgrade from 1.x version 💥

🗂️ Version Record Files 🗂️

🫶 The nvtake Command 🫶

🧚 The nvcmp Command 🧚

🌈 Configuration Files 🌈

⚙️ Configuration Table ⚙️

👑 Global Options 👑

🍓 List Options 🍓

🔎 Search in a Webpage 🔎

🦋 Search in an HTTP header 🦋

🔎 Search with an HTML Parser

🧃 Search with an JSON Parser (jq)

🐚 Find with a Command

📦 Check AUR

🐙 Check GitHub

🌈 RichResult metadata

🍵 Check Gitea

🦋 Check Gogs / Forgejo / Codeberg

🪣 Check BitBucket

💻 Check BitBucket

🦊 Check GitLab

🎀 RichResult metadata

🐍 Check PyPI

💎 Check RubyGems

📦 Check NPM Registry

🍓 Check Hackage

☕ Check Maven

🐪 Check CPAN

📊 Check CRAN

🎼 Check Packagist

🦀 Check crates.io

🏹 Check Local Pacman Database

🏛️ Check Arch Linux official packages

🌀 Check Debian Linux official packages

🧡 Check Ubuntu Linux official packages

🔍 Check Repology

🧚 Check Anitya

🤖 Check Android SDK

✨ Check Sparkle framework

🐙 Check Pagure

💅 Check APT repository

🍓 Check RPM repository

🦋 Check Git repository

🧚 Check Git repository without git CLI using pygit2

🌈 Check Git repository without git CLI using Dulwich

💖 Check Mercurial repository

🐳 Check container registry

✨ Check ALPM database ✨

✨ Check ALPM files database ✨

✨ Check Open Vsx ✨

✨ Check Visual Studio Code Marketplace ✨

✨ Check Go packages and modules ✨

✨ Check opam repository ✨

✨ Check Snapcraft ✨

✨ Combine others' results ✨

✨ Manually updating ✨

✨ Extending ✨

🫶 The `nvtake` Command 🫶

🧚 The `nvcmp` Command 🧚