Skip to main content

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 StaticProvider or a custom ReleaseProvider for 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)

Source distribution for uv-tool-updater 0.1.9
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)

Table of built distributions (wheels) for uv-tool-updater 0.1.9
File Interpreter ABI Platform Actions
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.

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