uv-tool-updater
English | 繁體中文
uv-tool-updater coordinates safe updates for Python CLI, desktop, and tray applications installed by uv tool install. It does not modify an environment itself: installation is delegated to uv tool upgrade, after the host process exits.
Status: early MVP (
0.1.9). The public API and result schema may evolve before 1.0.
Install
uv add uv-tool-updater
The host must provide a private state directory. This avoids imposing a platform-directory dependency and lets GUI applications use their existing settings location.
Interactive update smoke test
Install this project as a uv tool, then run the bundled test command:
uv tool install uv-tool-updater
show-version
show-version prints the installed version, checks PyPI, and asks before updating when a newer release exists. Only y or Y starts the normal external-helper update flow. The command exits, and uv tool upgrade uv-tool-updater==<verified-version> runs after that process has ended. Console commands restart in the background without an interactive terminal; invoke show-version again to display the saved result.
For an isolated test state directory, set UV_TOOL_UPDATER_STATE_DIR before running the command.
Before the project is published to PyPI, simulate release metadata with:
show-version --latest-version 0.1.9
This option changes only the metadata used by the version check. The update itself still uses the source saved by uv, while qualifying the requirement as uv-tool-updater==<verified-version>. For a local-path installation, change the project version and source first, while leaving the installed tool on the older version, then run the command with that newer version number.
A console command restarted by the background helper does not receive an interactive terminal. It exits without consuming the result; run show-version once more in the existing terminal to display the completed update result. GUI and tray applications still restart normally.
Minimal integration
import os
from pathlib import Path
from uv_tool_updater import UpdateStatus, Updater
updater = Updater(
package_name="fshot",
command_name="fshot",
state_dir=Path.home() / ".local" / "state" / "fshot" / "updates",
)
# Run this synchronous network operation on a worker thread in GUI applications.
check = updater.check()
if check.status is UpdateStatus.UPDATE_AVAILABLE and check.release is not None:
# The host must first save data or receive explicit permission to discard it.
session = updater.prepare_update(check.release, restart_args=[])
session.start_helper(host_pid=os.getpid())
# Only now ask the framework to quit normally.
On restart, use updater.consume_latest_result() (or consume a path returned by pending_results()). Consumption re-reads the actual installed distribution version; a zero uv exit code alone is never presented as proof that the version changed.
Guarantees and limits
- Python 3.10–3.14; Windows, macOS, and Linux.
- Public PyPI metadata by default; inject
StaticProvideror a customReleaseProviderfor tests/private indexes. - Stable releases by default; prereleases are opt-in.
- Automatic installation is refused outside a detected uv tool environment and for editable installs.
- The helper waits up to 10 minutes by default and never terminates the host.
- Failed upgrades restart the original command by default and preserve a local log.
- No telemetry and no GUI-framework dependency.
Documentation
Metadata
Release files for uv-tool-updater 0.1.9
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| uv_tool_updater-0.1.9.tar.gz | 69.8 kB | Without provenance | Details for uv_tool_updater-0.1.9.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| uv_tool_updater-0.1.9-py3-none-any.whl | Python 3 | none | any | Details for uv_tool_updater-0.1.9-py3-none-any.whl |
Total release size: 91.8 kB
Release files / uv_tool_updater-0.1.9.tar.gz
| Download URL | uv_tool_updater-0.1.9.tar.gz |
|---|---|
| Size | 69.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e7be84b772903ad8e5b4ebda1689d729260d43d2c2a2c4399e90b5e17e07437b
|
|
BLAKE2b-256 checksum How to use checksums |
938f0663c8ad45488ce374d2c59c3cd7e95f5adc4005fcbac62c6379c1e99544
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / uv_tool_updater-0.1.9-py3-none-any.whl
| Download URL | uv_tool_updater-0.1.9-py3-none-any.whl |
|---|---|
| Size | 22.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
95b7a4fa84aa4d6d2b8567bf61e59b4541a3013a9fa0606edf3e4afea89e60c0
|
|
BLAKE2b-256 checksum How to use checksums |
8e1130d3dcc2a018c70afe0013dc31febaae3cfe77b6279577f7f148061a4c78
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for uv-tool-updater 0.1.9
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.