pypi-cleanup-tui
A thin, visual skin over pypi-cleanup, which performs the actual deletion. Consider using:
- this TUI to cull per-version and visually: selecting by hand, with the survivors in view;
pypi-cleanupdirectly when cull rules are expressible and reusable (.*rc\d+, keep-newest, before-a-date), especially for automation across many packages.
Features
- A package's whole history in one table, with upload date and age in calendar days, so a stale release is visible at a glance.
- Mark with
x/X, clear withu/U-- a selection you can see, with no pattern to get wrong. - A stability gap (
g) unmarks the releases a newer one superseded too soon: what stays is what people actually installed. - Search (
/) over the versions; while a pattern is in force, the marking keys touch only the visible rows. - Move between packages with
p/P, between indexes withh, sort withs, change the date zone withz. - Every deletion is a dry run first, with the command and its report shown before a second confirmation; a read-only run browses with no delete key.
Installation
pipx install -f pypi-cleanup-tui # install or refresh; -f makes one command do both
pipx install -f pypi-cleanup # the tool the TUI hands the deletion to
Note: pipx gives the TUI its own environment; the package needs Python 3.11 or newer. The TUI exposes only part of
pypi-cleanup; run that tool directly for anything it lacks, and a read-only run browses without it installed.
Usage
Command line
pypi-cleanup-tui --user alice pack1,pack2 pack3
The first name is the package the table opens; the rest is kept for p and for the next run. Package arguments are cumulative: a run puts its names in front of the remembered list and drops duplicates.
| Featured Option | Meaning |
|---|---|
-u, --user |
the PyPI account, kept for the cleanup step; remembered |
--totp-method |
how the authenticator code is supplied; explained below; remembered |
--totp-dump |
for troubleshooting, show the current authenticator codes for comparison; Ctrl-C exits |
-h, --help |
see every option and the remembered values |
Main screen
| Key | Action |
|---|---|
q |
quit |
? |
open the help screen; ESC returns to the screen that opened it |
/ |
open the incremental search; ENTER closes it, ESC restores the pattern |
T |
open the THEMES screen (also from the help screen); ESC returns to the screen that opened it |
t |
cycle the color theme (THEMES and help screens; mono turns color off) |
p |
show the next package in the list and reload |
P |
open the package list |
h |
switch between pypi.org and test.pypi.org and reload |
f |
refetch the package; marks stay, and STALE clears once the index catches up |
x |
mark the picked release for deletion, then step down |
X |
mark the picked release and every release below it, then step up (unmarked row only) |
u |
unmark the picked release, then step down |
U |
unmark the picked release and every release below it, then step up (marked row only) |
z |
switch the DATE column between UTC and the local time zone (also on the help screen) |
s |
change the sort order |
d |
leave the table, run a pypi-cleanup dry run, then the deletion after a second confirmation |
g |
apply the stability gap on the table; on the help screen, rotate the gap instead |
The second header line names the run: User=..., [p]ack=... and [h]ost=...; host is the index key, not a domain. A bold STALE follows host= while the index has not caught up with a deletion (see below).
Marked releases take ✘ in DEL and dim; the releases that will be kept stay in the success color. T lists the palettes; its mono entry turns color off.
The column titles are the third header line, with a * on the sorted column and the zone named in DATE. A key block that does not apply is blanked, so nothing to its right moves:
x:mark X:mark▼ sort zone gap30 fresh quit ?:help / nothing marked, unmarked row
del unmark Unmark▼ sort zone gap30 fresh quit ?:help / marked, pick on a marked row
R/O unmark Unmark▼ sort zone gap30 fresh quit ?:help / read-only, d never offered
- An unmarked row offers
x/X; a marked row offersu/U. dleads once something is marked and no pattern is filtering; a read-only run showsR/Oinstead.frefetches the package: marks follow the versions the index still lists, andSTALEclears once a deletion is confirmed.
Search and the stability gap
/filters the version column with a case-insensitive regular expression;ENTERcloses it,ESCrestores the previous text, and a closed pattern limitsx,X,uandUto the visible rows. An empty or invalid pattern leaves the table unfiltered.- On the help screen
gpicks the stability gap; on the table it applies it, unmarking every marked release that a newer release superseded within the gap. Days are calendar days in the zonezshows, the newest release counts as stable, and the choice is remembered.
Package screen
P opens the package list, whose rows are also what p rotates through:
PACKAGES x:remove ESC:open ?:help
PACKAGE VERs DELs
✓ alpha 3 0
✓ beta 2 0
gamma - -
- Each row shows whether the package was visited (
✓), its name, its last known version count and this run's delete count. ESCopens the highlighted package in the table.xremoves the highlighted package from the TUI's list, not from the index.
Running pypi-cleanup
A normal run first checks that pypi-cleanup, which performs the actual deletion, is installed, and stops with a hint when it is missing. A read-only run skips that check and shows R/O where del would be.
Pressing d leaves the table for the bare terminal, runs a --query-only dry run, then asks again before the --do-it deletion. Note that:
- Each question takes
yes,no, or a bareENTERfor the safe answer (yes to the dry run, no to the deletion). - The printed command is a description, not meant to be copied; a long version pattern is broken after its
|alternations. - When a scoped password supplies a value, a line above the command names the mapping, never the value.
- If you provide
$PYPI_CLEANUP_TOTP_SECRET, then--totp-methodchooses how this TUI assists providing the 6-digit code:expect(default) runspypi-cleanupunderpexpect; you answer prompts until the "Authentication code:" prompt where you pressCtrl+]for the TUI to answer.autoprovides the code w/o manual intervention; you must set$PYPI_CLEANUP_PASSWORD, too.printshows the code and its remaining lifetime above each run; you type it at the prompt (be quick or it may expire).offleaves answering entirely to you; same behavior as no$PYPI_CLEANUP_TOTP_SECRET.
A successful deletion hides the deleted versions and and re-fetches the version list. If the fetched list has deleted versions (its CDN can lag), a bold STALE appears in the header until f finds the a new version list credibly up-to-date; switching the packages or host drops the STALE indicator.
Hints for credentials (to reduce interactive prompts)
- Set
$PYPI_CLEANUP_USER4PYPIand$PYPI_CLEANUP_USER4TESTto override the run's user per index (only needed if the two user names differ).- Set
$PYPI_CLEANUP_PASSWORDto your account's login password to avoid thepypi-cleanuppassword prompt.
- If the pypi and test passwords differ, scope them by appending
4PYPIor4TESTto the names, and this TUI overrides$PYPI_CLEANUP_PASSWORDaccording to scope.- Set
$PYPI_CLEANUP_TOTP_SECRET(and/or its scoped forms) to let this TUI supply the 6-digit code per the--totp-method.
Options are remembered
Your package list, sort order, date zone, gap, theme, user, index and TOTP method persist in ~/.config/pypi-cleanup-tui/config.ini, so a bare pypi-cleanup-tui starts with your previous options. Read-only mode is never remembered.
pypi-cleanup-tui newpack # newpack, then the stored names
pypi-cleanup-tui pack2 # an already stored name keeps its position
? lists the saved options and the file they came from.
Troubleshooting and Precautions
- Stale Version Lists: the TUI asks the index not to cache, but a proxy or corporate network can still serve old data for up to 15 minutes.
frefetches; after a deletion the header showsSTALEuntil the index stops listing the deleted versions. - Authenticator/TOTP (Time-based One-time Password) Failures: if the TUI's codes are rejected, check the machine's clock is NTP-synced and compare the dumped codes with your authenticator app. If the times agree but the codes do not, recheck the secret.
- General Credential Failures: If
pypi-cleanupfails with an authentication or unrecognized device error (initially or later), log intopypi.organd/ortest.pypi.orgfrom a browser on this same machine and choose to remember the device for 30 days.
License
This project is licensed under the MIT License. See the LICENSE file for details.
Metadata
Release files for pypi-cleanup-tui 1.0.0
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 |
|---|---|---|---|---|
| pypi_cleanup_tui-1.0.0.tar.gz | 82.2 kB | Without provenance | Details for pypi_cleanup_tui-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pypi_cleanup_tui-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for pypi_cleanup_tui-1.0.0-py3-none-any.whl |
Total release size: 131.5 kB
Release files / pypi_cleanup_tui-1.0.0.tar.gz
| Download URL | pypi_cleanup_tui-1.0.0.tar.gz |
|---|---|
| Size | 82.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ca4f2781d97fcaef3cae5e81502aa0b2272927776906b01da36106662a3b67e7
|
|
BLAKE2b-256 checksum How to use checksums |
710cd3e7feec8056a8b5d26a9b303ddd48db91e57b3e6e545e5a465d1b475719
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.5
|
Release files / pypi_cleanup_tui-1.0.0-py3-none-any.whl
| Download URL | pypi_cleanup_tui-1.0.0-py3-none-any.whl |
|---|---|
| Size | 49.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b8c67f826ccfd2fee87d61488b7f315cbe5772fd058ff0fc97cdb5b734abc247
|
|
BLAKE2b-256 checksum How to use checksums |
2f38c1f0c926a64686dbbef3f7f8f76ddfb6fae7b353bfb9f3d9cadc468f7bbf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.5
|
Security for pypi-cleanup-tui 1.0.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.