feat: warn when a newer version is available

[joshyam-k]

Print a warning message to stderr when a newer version of the cli is available.

Intent

Fixes #779

Type of Change

• Bug Fix
• New Feature
• Breaking Change

Approach

• check PyPI for a newer version (only on deploy commands) and print the upgrade hint on every exit path, including failed/fast-failing deploys
• cache the result on disk with a simple 24H TTL.
• the fetch runs in a background thread; only a cold cache waits on it (bounded by a 2s PyPI timeout) otherwise the failure can beat the fetch and the warning message is never printed.
• fail silently: if the fetch errors or doesn't finish within the timeout, the deploy proceeds with no hint (and no error)
• scoped to deploy only, so quick commands like list/info never pay the cold-cache wait.
• can be disabled via RSCONNECT_DISABLE_VERSION_CHECK=1

Automated Tests

Unit tests for each new helper in isolation and also a TestCLIIntegration test that tests the feature end-to-end through the cli.

Checklist

• I have updated CHANGELOG.md to cover notable changes.
• I have updated all related GitHub issues to reflect their current state.
• I have run the rsconnect-python-tests-at-night workflow in Connect against this feature branch.

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://posit-dev.github.io/rsconnect-python/pr-preview/pr-795/
Built to branch gh-pages at 2026-06-26 15:12 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[github-actions]

☂️ Python Coverage

current status: ✅

Overall Coverage

Lines	Covered	Coverage	Threshold	Status
7373	6047	82%	0%	🟢

New Files

File	Coverage	Status
rsconnect/version_check.py	83%	🟢
TOTAL	83%	🟢

Modified Files

File	Coverage	Status
rsconnect/main.py	80%	🟢
TOTAL	80%	🟢

updated for commit: 356e8b6 by action🐍

[marcosnav]

This is a great addition. I have some usability feedback, I forced the output from _fetch_latest_version and while trying this out I noticed that the new version warning message only triggers on successful deployments.

For example, a project with missing requirements.txt shows this (no warning about a new version):

It seems that any error that goes through the exception handler (which covers RSConnectException and general Exception) calls sys.exit(1) and the warning never prints.

So in practice, you'd only see the version warning after a successful deploy (or possibly a very late failure like a task timeout on the server side).

That seems like a significant gap, users that most likely could benefit from "hey, upgrade" are the ones hitting bugs that were already fixed.

Also, how complicated is to have this warning for all commands info, version, list...?

[joshyam-k]

@marcosnav huh good catch I thought I fixed that. My guess is maybe on fast failures the error beats the fetch command and so we don't get the warning.

[joshyam-k]

@marcosnav okay I figured out the issue and it stems from an issue that we have to resolve in what our approach is here.

There are 3 things we want with this feature:

1. Warn on every exit path
2. Warn even with no cache
3. Do not block on the check

The issue is that 2 and 3 are actually at odds with each other because if there is no cache (i.e first time running it in over 24h) then the check must be blocking in order to fire before the command finishes (in the case of a fast failure i.e missing requirements.txt)

Maybe the best we can do here to satisfy all criteria is to make the check blocking but only when the cache is empty. Otherwise there's just no way around avoiding the case that you caught above.

[marcosnav]

then the check must be blocking in order to fire before the command finishes (in the case of a fast failure i.e missing requirements.txt)

@joshyam-k Just to confirm, by blocking you mean a synchronous wait on the version check right? If that is the case I think it is ok to wait. Maybe just to avoid hanging issues, we could have a timeout of about 3s to the PyPI check and discard the check if it takes longer than that so the command continues. WDYT?

[joshyam-k]

@marcosnav yes correct. And if we go that route I'm even more inclined to keep this scoped to just deploy commands. We don't want multi second latency on things like rsconnect list just because we are blocking on checking the version. In deploy we usually can just hide behind what is already a multi-second process.

[marcosnav]

@joshyam-k Yes, that sounds right. BTW, there is already a _PYPI_TIMEOUT_SECONDS = 2 so ignore my timeout comment, it is already there.

[joshyam-k]

@marcosnav ok ready for another look!