Skip to main content

pyselfupdate

Self-update and update notification for Python CLIs installed with uv tool.

A CLI installed with uv tool install has no way to tell its user that a newer release exists, so it silently drifts. This package adds two layers, used independently. notify prints one line, at most once a day, when a newer release exists. update installs that release when the user asks.

uv tool upgrade re-resolves the requirement a tool was installed with, so a tool installed at a release tag stays at that tag. update asks the release source which tag is newest and reinstalls at that tag. A git install is held to that tag's uv.lock. A tool installed from a package index is offered only the version its index serves, which can trail a release whose upload has not finished.

The package has no runtime dependencies. It uses urllib for the network, tomllib for uv's receipt and lock, and its own semver implementation. CI installs it alone into an empty virtual environment and imports every module except the typer integration.

Install

uv add pyselfupdate            # the library alone, with no dependencies
uv add 'pyselfupdate[typer]'   # adds typer and the ready-made `update` command

The supported Python versions are requires-python in pyproject.toml, which uv checks before it installs. The floor is the first release carrying tomllib.

Starting from scratch

Wire both layers into a typer CLI. tool is the name uv tool install gives the tool, and owner is the GitHub account its releases are published under.

import typer

from pyselfupdate import Config, notify
from pyselfupdate.typercmd import add_update_command

app = typer.Typer()
CONFIG = Config(tool='mytool', owner='you')  # releases at github.com/you/mytool


@app.callback()
def main() -> None:
    notify(CONFIG)  # never raises; ignore what it returns


add_update_command(app, CONFIG)  # registers `mytool update`

Then publish a release, install the tool at its tag, and ask it:

gh release create v1.0.0 --generate-notes  # a GitHub release, not a bare tag
uv tool install 'mytool @ git+https://github.com/you/mytool@v1.0.0'  # at a tag, never a branch
mytool update --check                      # ✓ mytool already at latest: v1.0.0

The running version is read from the installed distribution's metadata, so a release's tag has to match the version its package declares. A tool versioned from its git tags gets that for free.

The install names a tag because an install from a branch, a commit or a local checkout is never updated. Its version says nothing about how far behind it is. What may be updated lists every case.

A private repository needs a credential. gh auth login is enough, because the check runs gh auth token by default.

When the notice never appears, run mytool update --check first. It runs the steps that can fail and prints what stopped it. Those are reading uv's receipt, asking the release source and, for an index install, asking its index. The notice stays silent on each. Every other reason it stays silent is in the table under notify.

notify — one line after the command's output, never an error

Once per 24 hours, when a newer release can be installed, one line goes to stderr:

mytool v1.4.0 available (running v1.3.2) — run `mytool update`

By default the line is printed at interpreter exit, so it lands after the command's own output rather than inside it.

notify never raises, never installs anything, and never prints an error. A check that fails is recorded in the state file and swallowed, because an update notice must not be able to break the command the user typed.

Nothing is printed when any of these hold:

Condition Why
NO_AUTO_UPDATE or MYTOOL_NO_AUTO_UPDATE is set Opted out
--help or -h comes before any -- on the command line typer runs the callback even for a subcommand's help screen, which is not work
stdout or stderr is not a terminal mytool list > out 2>&1 must stay clean
A variable in pyselfupdate.notifier.CI_VARIABLES, such as CI, is set Not a human
Installed from a local path, an editable checkout, a branch or a commit Nothing to compare against
Checked within the interval One request per interval, not per invocation

The opt-out is presence-only, so NO_AUTO_UPDATE=0 disables the notice, the same way NO_COLOR works. The interval has its own pair, MYTOOL_AUTO_UPDATE_INTERVAL falling back to AUTO_UPDATE_INTERVAL. Each takes 30m, 6h, 7d or a bare number of seconds. The tool's form of each variable is its name uppercased, with - written as _.

A command writing into a pager, a log or a structured-output mode calls notify(config, interactive=False). Nothing about the streams reveals that.

update — rebuilds the environment it runs in, so it runs last

update runs uv tool install --force, which rebuilds the virtual environment the running interpreter lives in. Replacing a Unix binary leaves a running process untouched, because the process holds an inode. Rebuilding a venv pulls modules out from under a live interpreter, so anything imported afterwards can fail in ways that are hard to read.

So make update the last thing the process does, then call exit_now. Or call update_and_reexec, which replaces the process with the release it installed, running the same command line. update_and_reexec writes lock_warning to stderr itself before the re-exec, because its caller never sees the Result.

check reports what update would install, and installs nothing:

from pyselfupdate import Config, check, require_updatable

config = Config(tool='mytool', owner='you')

require_updatable(config)  # reads uv's receipt; raises on an install update refuses
result = check(config)  # asks the release source, and an index install's index
if result.update_available:
    print(result.current, '->', result.latest)

check compares the running version with the newest version an update can install. It reads uv's receipt to learn where that version comes from, and refuses nothing the receipt describes. A branch build's version can rank below the release it is ahead of. Three commits past v1.2.3, a tool versioned from git tags builds as 1.2.3-post.3+<commit>, which semver ranks below v1.2.3. So call require_updatable before reporting what check found. It refuses every install update refuses.

The typer extra carries the whole command. add_update_command(app, config) registers mytool update. run_update(config, check_only=...) is the same reporting, for a CLI that declares the command itself. Both read the receipt before the network, so mytool update --check refuses the same installs update does, printing the refusal and exiting 1. Both fetch the changelog before the install, because nothing can be imported after it.

A caller that needs its own steps between the check and the install composes the three pieces update is made of:

import sys

from pyselfupdate import Config, changelog, check, exit_now, install_release, require_updatable

config = Config(tool='mytool', owner='you')

installation = require_updatable(config)  # refuses before any request
result = check(config)  # the network, while the environment is intact
notes = changelog(config, result.current, result.latest)  # fetched before the install, printed after
installed = install_release(config, result, installation)  # a no-op when nothing is newer
print('\n'.join(notes))
if installed.lock_warning:
    print(installed.lock_warning, file=sys.stderr)
exit_now()  # flushes, then exits without unwinding through code that may import

Every error is a SelfUpdateError, and each cause has its own subclass, so a caller matches a type rather than message text:

Error Raised when
InvalidConfigError tool is empty, or owner is empty without a custom source
LocalInstallError The install is a local checkout, a branch or a commit, or the running version is not a semantic version
NotInstalledError uv's receipt is missing or unreadable, or holds a --with requirement an update would drop
NoReleaseError The source publishes no release, or its newest tag is not a semantic version
SourceError The source could not be reached, or answered with something unusable
SelfUpdateSourceFailure A SourceError from a transport or protocol failure, as opposed to a missing release
RateLimitedError A SelfUpdateSourceFailure for a spent rate limit. authenticated says which ceiling, and resets_at when it lifts, or None
LockUnreadableError The release's uv.lock could not be read, so nothing was installed
IndexUnreadableError uv could not say which version an index install's package index serves, so nothing was offered
InstallFailedError uv tool install ran and failed, or uv is not on PATH

A git install is held to the release's uv.lock

uv tool install never reads a lock. Handed a git requirement, it resolves every dependency to its newest version, so a tool would run on a set its CI never tested. update therefore clones the release's tag and exports its uv.lock. It passes registry pins as --constraints, and URL pins, such as a git dependency, as --overrides. uv records both in the tool's receipt, so a later uv tool upgrade stays held to them.

The tag What update does
Carries a uv.lock Installs the locked versions
Carries none Installs unlocked and sets lock_missing. lock_warning names the tag, and run_update and update_and_reexec print it
Will not clone, uv will not export its lock, or git or uv is not on PATH Raises LockUnreadableError and installs nothing

A tool that is one member of a uv workspace installs as git+<repo>@<tag>#subdirectory=<member>. update keeps the subdirectory, and reads the workspace's one uv.lock at the repository root for that member's dependencies alone.

An update reinstalls the tool's own extras, as in mytool[fast], with their dependencies held to the lock. Every --with and --with-editable requirement is passed back to uv as well.

uv tool install --force reads nothing back from the receipt it replaces. So an update passes back the receipt's --python and the flags naming where its packages come from: --index, --default-index, --index-url, --extra-index-url, --find-links, --no-index, --index-strategy and --keyring-provider. Without them, a tool installed with --index https://pypi.example.com/simple/ resolves its update against PyPI alone and is not found. An explicit index is left out, because only a config file can declare one and the reinstall reads that file again. Dropping any other recorded option changes how the tool resolves or builds, never whether it is found.

An index install is offered only what its index serves

A release exists on GitHub before its upload to the package index finishes, and stays there when the upload fails. So for an index install check asks the index too, through uv. It runs uv pip compile --no-deps on the tool's name with the flags above, so uv reads the index with the configuration and credentials the reinstall uses. The version uv names becomes latest, and index_latest holds it.

The index serves What check reports
The newest release latest is that release
Another version latest is the index's version, or current when that is not newer. index_warning names both versions, and run_update and update_and_reexec print it
Nothing uv can read within Config.timeout seconds Raises IndexUnreadableError

An install from an index reads no lock, because a wheel carries none. It takes the index's version as a floor, mytool>=2.0.0, rather than a pin. uv records the specifier in the receipt, and uv tool upgrade refuses to move an exact pin.

What may be updated is read from uv's receipt, not guessed from the version

uv writes uv-receipt.toml into the tool's directory at install time. It records where the tool came from, which the running program cannot know:

Receipt Result
git = "...git?rev=v1.2.3" Updatable
name = "mytool" (from an index) Updatable
git = "...git" with no rev Refused: it tracks the default branch, so its version says nothing about how far behind it is
git = "...git?rev=main", or a rev naming a commit Refused: uv writes rev= for whatever followed the @, so a rev counts as a release only when it is tag_prefix followed by a semantic version
directory, path or editable Refused: reinstalling would discard a working copy
A --with requirement no requirements-file line reproduces, such as a relative path Refused with NotInstalledError: the update would drop it

update and mytool update --check refuse every row marked Refused. The notice stays silent on each of them except the --with row, because a newer release is still worth knowing about there.

A tool whose receipt is missing or unreadable fails closed. The notice treats it as local, and update raises NotInstalledError.

A caller with a custom source whose refs carry a prefix sets tag_prefix to match. Without it, a tag install from that source is refused as a branch install.

Config — the tool's name, and every default derived from it

from pyselfupdate import Config

config = Config(
    tool='mytool',  # required: the uv tool name, the state directory, the variable prefix
    owner='you',  # GitHub owner; required unless source is given
    repo='mytool',  # defaults to tool
    package='mytool',  # the distribution the version is read from; defaults to tool
    version='1.2.3',  # defaults to that distribution's installed metadata
    token='',  # see Authentication below; you almost certainly want the default
    token_func=None,  # a source of your own, tried before $GITHUB_TOKEN_COMMAND
    timeout=10.0,  # seconds per read: the release source's, and uv's read of an index
    tag_prefix='',  # 'cli/' for tags like cli/v1.2.3
    allow_prerelease=False,
    source=None,  # a custom Source; defaults to a GitHubSource built from the fields above
)

source is the seam for releases published somewhere other than GitHub. A Source is anything with latest_release() returning a Release. A source that also has changelog(from_ref, to_ref), returning commit subjects, gets a changelog in mytool update. One without it gets none, and that is not an error.

Authentication — on by default, through gh auth token

Configure nothing. GitHubSource runs gh auth token when a request is about to be made, and sends what it prints.

The alternative is not "no credential". It is 60 requests an hour, charged per IP address and shared with every other anonymous caller behind the same egress. A default that has to be opted into is a default nobody sets.

Four sources, first non-empty wins:

Source Set by Default
Config.token you, in code unset
$GITHUB_TOKEN, then $GH_TOKEN whoever runs your CLI unset
token_func() you, in code unset
$GITHUB_TOKEN_COMMAND whoever runs your CLI gh auth token

$GITHUB_TOKEN_COMMAND both redirects and disables, which is what a switch has to do to be worth having:

GITHUB_TOKEN_COMMAND='pass show github/token'   # use this instead
GITHUB_TOKEN_COMMAND='op read op://vault/gh/token'
GITHUB_TOKEN_COMMAND=''                         # run nothing, stay anonymous

It never raises. A command that is not installed, exits non-zero, or takes longer than ten seconds degrades to an unauthenticated request, which still works against a public repository.

token_func is for a credential neither the environment nor a command can produce. It is called lazily, for the same reason the command is. The notify gate resolves a Config on every invocation and declines most of them without reaching the network, and a subprocess in front of that gate is the entire cost worth avoiding.

The variable names and the default command belong to GitHubSource, not to Config. A credential is the host's business. A Source for another code host brings its own variable and its own command, and nothing above the Source protocol learns either name.

State — one file per tool per machine, stamped before the network call

${XDG_STATE_HOME:-~/.local/state}/<tool>/autoupdate-<machine>.json, written atomically:

{
  "tool": "mytool",
  "schema": 1,
  "checked_at": "2026-07-26T15:07:15Z",
  "checked_at_epoch": 1785078435,
  "current_version": "v1.3.2",
  "latest_version": "v1.4.0",
  "last_error": ""
}

State, not config and not cache: it persists across runs, it is not authored by the user, and deleting it changes behavior rather than merely costing a recompute. That is XDG_STATE_HOME by the Base Directory specification, and it is where gh puts the same thing.

<machine> is the bare hostname, domain dropped and lowercased, from pyselfupdate.state.machine(). It is unknown when the hostname cannot be read. It is in the name because both fields that vary describe one machine: the version installed here, and the instant this box last checked. A state directory shared between machines, by a file syncer or a network home directory, otherwise has two writers on one path. It reports whichever wrote last as the state of all of them.

The timestamp is written before the network call. gh stamps only on success, so a rate-limited or offline user re-hits the API on every invocation until the window resets. An interval exists to bound the request rate, and only this ordering does that.

A gate that declines to check writes nothing, so a missing file means the network was never reached. A check that failed leaves its error in last_error. read_state('mytool') reads the file back.

Siblings — the same two layers for a Go binary and a git checkout

All three carry both layers. They share the autoupdate-<machine>.json schema, the machine derivation that names it, and the NO_AUTO_UPDATE and AUTO_UPDATE_INTERVAL variables. They do not share an API, because "update" means a different operation in each.

Version precedence is deliberately identical across all three, so a tool and its siblings never disagree about which release is newer.

License

MIT

Metadata

Release files for pyselfupdate 0.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyselfupdate 0.8.0
File Size Uploaded Provenance Actions
pyselfupdate-0.8.0.tar.gz 38.9 kB Without provenance Details for pyselfupdate-0.8.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pyselfupdate 0.8.0
File Interpreter ABI Platform Actions
pyselfupdate-0.8.0-py3-none-any.whl Python 3 none any Details for pyselfupdate-0.8.0-py3-none-any.whl

Total release size: 83.2 kB

Release files / pyselfupdate-0.8.0.tar.gz

Download URL pyselfupdate-0.8.0.tar.gz
Size 38.9 kB
Tags Source
SHA-256 checksum
How to use checksums
c3fc80920b851d7d4763b055a095567a595b5408192a4fd3dbba0731ec0b7180
BLAKE2b-256 checksum
How to use checksums
f814e0be3762990c8178c541b1628351636d738da15d6d1f5d204c8b2d933bfd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.24 {"installer":{"name":"uv","version":"0.12.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / pyselfupdate-0.8.0-py3-none-any.whl

Download URL pyselfupdate-0.8.0-py3-none-any.whl
Size 44.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3be39b4bd2c6fce3c944739a3001a5b788c1f5e76dc6eff951eb41640dd2f150
BLAKE2b-256 checksum
How to use checksums
33e564457d8d7130a253e0ffff50079e1211373d22c6a91f523b445ab47d4040
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.24 {"installer":{"name":"uv","version":"0.12.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for pyselfupdate 0.8.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page