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 in a background thread (only on deploy commands)
• cache with a simple 24H TTL
• fail silently (don't block deploys if the PyPI fetch fails for some reason)
• can be disabled via RSCONNECT_DISABLE_VERSION_CHECK

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-24 21:26 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
7361	6022	82%	0%	🟢

New Files

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

Modified Files

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

updated for commit: ab9011c 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.