nvchecker: a version checker that watches release feeds for you

One question, asked repeatedly

nvchecker is short for new version checker, and the readme states its purpose in a single sentence: it is for checking if a new version of some software has been released.

That narrowness is the design. There is no update mechanism, no dependency resolver, no version constraint solver and no package management. The tool looks at the places where projects announce releases, decides what the newest version is, and tells you.

The audience follows from that. It is a distribution maintainer who needs to know when upstream projects move, an infrastructure team that tracks the versions of the tools it deploys, and a developer with a list of applications to keep an eye on. The readme refers to the files it works with as version record files, and the topics attached to the repository name the same territory: package tracker, packaging, release helper, software.

Two things make it more than a scraper. The first is that the checks are described declaratively, in configuration files, rather than hard coded. The second is that the definition of where a version lives is separated from the definition of what to check, which is what lets one tool watch a hundred different projects whose release pages have nothing in common.

The project is MIT licensed, written in Python, and the current branch is version 2.0, with the older 1.x line kept on a separate v1.x branch for anyone still running it.

Two directories: the checker and the sources it knows about

The top level of the repository makes the split visible. There is an nvchecker directory holding the checker itself, and an nvchecker_source directory beside it, which is where the version source definitions live.

That separation is the important architectural decision. A version source is the part that knows how a particular project announces releases: the shape of its download page, the pattern of its file names, the tag format in its repository. The checker is the part that runs those definitions, normalises the answers and reports them.

The consequence for a user is that you write a configuration file that names the sources you care about, and the sources themselves come from the maintained set rather than from your own configuration. There is a sample_config.toml at the root of the repository to start from, and the readme tells you that you normally want to specify some version record files, which is how a run is given its list of things to check.

The files are in TOML, which is consistent with the dependency list, since tomli is a declared dependency on Python versions before 3.11, where the standard library has no TOML parser. A configuration format with a parser in the standard library from 3.11 onward is a sensible choice for a tool meant to be dropped into CI.

There is also a keyfile.toml.enc at the root. An encrypted TOML file in a version checker repository is the sort of detail that tells you some sources need credentials, and that the project provides a way to keep them out of the repository in plain text.

The HTTP stack, and the commands your configuration depends on

The dependency section is unusually explicit, and it is the clearest statement of what the tool needs at runtime.

The base requirements are Python 3.9 or newer, and three libraries: structlog for structured logging, platformdirs for platform specific directories, and tomli on Python versions below 3.11.

Then there is the HTTP layer, and here the readme does something unusual: it lists combinations rather than a single requirement, ordered by preference.

The first choice is tornado together with pycurl. The second is aiohttp. The third is httpx with HTTP2 support, which is marked as experimental and supported only in its latest version. The fourth is tornado on its own.

Listing alternatives rather than one dependency is a deliberate signal about the project's priorities. A version checker makes a lot of small requests to a lot of different servers, some of which are slow, some of which are behind awkward TLS setups, and the HTTP client is the component most likely to decide whether a run works in a corporate network. Offering several combinations means the tool can run in an environment where only one of them is installable, with pycurl for the environments where curl's TLS stack is the one that is allowed through a proxy.

The last dependency line is the one that catches people out. All the commands used in your software version configuration files are required. If your configuration tells the checker to run a program to find the newest version, that program has to be installed on the machine doing the checking, and the README lists this as a dependency rather than an optional extra.

Installing it and running the first check

There are two install routes, and the difference between them is whether you want the released version or the code in the repository.

  pip3 install nvchecker

If you want the latest code, the readme says you can clone the repository and run pip install . instead.

  pip install .

Once it is installed, the help option lists what is available.

  nvchecker --help

And the actual work is a run with one or more software version files, which the readme shows as a configuration file passed with the -c option.

  nvchecker -c config_file

So the shape of a session is short. Install, point it at a configuration that names the software you track, and read the report. There is no daemon, no database and no state to manage between runs, which is what makes it usable from a cron job or a CI job without ceremony.

The detailed documentation is on readthedocs, at nvchecker.readthedocs.io, and the readme points there for anything beyond the three commands above. The packaging status is tracked on repology, so the tool is visible across the distributions that package it, and the badges show the test workflow, the PyPI version, the documentation build and the repology status.

The 2.0 branch and the tooling around it

The branch layout tells you that this is a project with a substantial 1.x history, and the readme points users of the older line to the v1.x branch. The 2.0 line is the current work, and the packaging metadata shows it is a conventional modern Python project built with setuptools.

The pytest configuration is short but says something useful. The asyncio mode is set to strict, and the default fixture loop scope is set to session, which tells you the asynchronous tests share one event loop across the session rather than creating one per test. That is a deliberate choice for a tool whose unit tests mock a lot of HTTP.

[tool.pytest.ini_options]
# addopts = -n auto
asyncio_mode = "strict"
asyncio_default_fixture_loop_scope = "session"

The comment on the addopts line is a disabled parallel test option, which is the sort of thing that gets left behind after a run on a loaded machine.

Around that there is a mypy.ini for type checking, a tox.ini for environments, a setup.cfg, a scripts directory and a tests directory, and a .typos.toml for the spell checker, which is the same tool many of the author's other projects use. The build and upload commands are left in the pyproject file as a comment, showing the release sequence of building without isolation, checking with twine and then uploading.

The encrypted keyfile.toml.enc deserves a mention again, because it is the piece that tells you the tool has a concept of credentials. Some version sources need a key or a token to query, and the project provides an encrypted file rather than asking you to keep secrets in the configuration you commit.

Where nvchecker is the wrong tool

Four limits, and the first is the one most people discover on day one.

nvchecker tells you that a new version exists. It does not upgrade anything, and there is nothing in the readme about applying a result, opening a pull request or pinning a dependency. If what you want is the upgrade rather than the information, this is the wrong tool, and a package manager or a dependency bot solves the problem more directly.

The second is that a source definition has to exist for the project you care about. The check for a given piece of software is implemented somewhere, either in the maintained source set or in your own configuration, and for an obscure project or a self hosted one you are writing that logic yourself. The readme does not describe a general fallback for a project with no definition.

The third is the dependency on external commands. The readme lists all the commands used in your software version configuration files as a dependency, so a configuration that shells out to, say, a version manager requires that manager on every machine that runs the check. That is a reasonable design for a tool that wants to reuse existing ecosystem tools, and it is a real constraint when the check runs in a minimal container.

The fourth is the branch split. A 1.x user and a 2.0 user have different tools with different behaviour, and the readme treats that as a fact rather than as a compatibility promise. The http2 option in httpx is also marked as experimental and supported only at the latest version, so pinning an older httpx removes a supported configuration.

Licence, maintenance and what to verify before adopting

The licence is MIT, with the licence file at the root of the repository, so the code can be used, modified and redistributed with the notice kept. This is not legal advice, and a company with a licence review process should still run its own check.

On maintenance, the last push was on 2026-10-11 and the repository is not archived. The project publishes no GitHub releases, so there is no tag history to consult, and the version you get depends on whether you install from PyPI or clone the repository. The badges show a test workflow, and the documentation build is tracked on readthedocs, which together suggest the project is built continuously rather than released on a schedule.

For an adopter, the verification list is short. Look at sample_config.toml in the repository and decide whether the configuration format matches how you would describe your sources, because that is the interface you will live with. Then check the HTTP side, since the dependency list expects one of several client combinations and a corporate environment may allow only one of them. Then confirm that the programs your definitions rely on are installed wherever the check will run, because the readme counts them as dependencies.

If those three things line up, the tool does exactly one thing, does it on every run, and gives you a report rather than a side effect, which is a reasonable bargain for a scheduled job that tells you your upstream world has moved.

Editorial conclusion

nvchecker is the right tool for a distribution team that needs to know when dozens of upstream projects publish a release, and for anyone who wants a single command that reports the newest versions instead of a dozen release feeds to watch. It is the wrong tool if you need an automatic upgrade, if you want the version data for software whose release page has no machine readable form, or if you are on the 1.x API and expect the 2.0 behaviour. Before adopting, look at the sample_config.toml in the repository to see whether the format matches how you describe your sources, and check the HTTP backend you have installed, since the choice between tornado with pycurl, aiohttp and httpx changes what you have to install.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. lilydjwg/nvchecker on GitHub
4. README