Topgrade (topgrade-rs) – kompleksowe aktualizowanie systemu w jednym poleceniu

Jedno polecenie. Wszystkie menedżery pakietów. Każda platforma. Kompletny przewodnik po narzędziu, które na zawsze zmienia sposób, w jaki aktualizujesz swój system.

Spis treści

1. Czym jest Topgrade?
2. Historia projektu
3. Dlaczego Topgrade jest lepszy od zwykłej aktualizacji?
4. Instalacja – wszystkie platformy
5. Podstawowe użycie i flagi
6. Konfiguracja (topgrade.toml)
7. Przykłady użycia – scenariusze
8. Zdalne wykonywanie przez SSH
9. Automatyzacja – cron i systemd
10. FAQ – najczęstsze pytania
11. Podsumowanie

Czym jest Topgrade?

Topgrade to wieloplatformowe narzędzie wiersza poleceń (CLI), napisane w języku Rust, które rozwiązuje jeden z najbardziej irytujących problemów codziennej pracy z komputerem – konieczność ręcznego uruchamiania dziesiątek różnych komend aktualizujących pakiety z różnych źródeł.

Kiedy pracujesz jako programista lub administrator systemu, twój komputer posiada zazwyczaj nie jeden, a kilkanaście menedżerów pakietów jednocześnie: systemowy apt lub pacman, Homebrew na macOS, cargo dla narzędzi Rust, pip dla Pythona, npm dla Node.js, a do tego wtyczki Vim, rozszerzenia VSCode, narzędzia Flatpak, firmware LVFS i wiele więcej. Utrzymywanie tego wszystkiego w aktualności ręcznie to koszmar.

 

 

Topgrade automatycznie wykrywa, które narzędzia i menedżery pakietów są zainstalowane na twoim systemie, a następnie uruchamia odpowiednie komendy aktualizacyjne dla każdego z nich – wystarczy jedno polecenie:

topgrade

To wszystko. Topgrade zajmie się resztą.

Kluczowa korzyść

Topgrade nie zastępuje twoich menedżerów pakietów – jest orkiestratorem, który je wszystkie wywołuje w odpowiedniej kolejności, prezentując wyniki w czytelnym, kolorowym interfejsie terminalowym.

Co Topgrade potrafi zaktualizować?

Lista obsługiwanych narzędzi i menedżerów pakietów jest imponująca i obejmuje między innymi:

Systemy Linux

apt, pacman, yum, dnf, zypper, portage, xbps, nix, guix, snap, flatpak i wiele innych

macOS

Homebrew (brew upgrade + brew cask upgrade), MacPorts, App Store przez mas-cli

---

Windows

Winget, Chocolatey, Scoop, Windows Update (przez PSWindowsUpdate)

---

Języki programowania

cargo (Rust), pip/pipx (Python), npm/yarn (Node.js), gem (Ruby), go, composer (PHP), opam (OCaml)

---

Edytory i IDE

Vim/Neovim (pluginy), Emacs (DOOM/Spacemacs), VSCode (rozszerzenia), JetBrains Toolbox

---

Narzędzia dev

rustup, ghcup, asdf, mise, conda, poetry, rye, uv i środowiska wirtualne

---

Shell

Oh My Zsh, Prezto, antigen, zplug, antibody, fish (wtyczki), bash-it, zr

---

Firmware

LVFS/fwupd – aktualizacje firmware urządzeń bezpośrednio z terminala

Historia projektu Topgrade

Historia Topgrade zaczyna się od frustracji – tej samej, którą zna każdy doświadczony użytkownik Linuksa czy macOS. Oryginalny projekt stworzył r-darwish (Roey Darwish), programista który – jak wielu z nas – miał dość uruchamiania tych samych długich sekwencji komend po każdym ponownym uruchomieniu systemu.

Pierwsza wersja pojawiła się na GitHubie jako projekt napisany w Pythonie, a następnie przepisany w całości na Rust – co przyniosło szybkość natywnych binariów, doskonałą obsługę błędów i możliwość łatwej dystrybucji jako pojedynczy plik wykonywalny bez zależności.

Projekt szybko zyskał popularność w społeczności open source ze względu na swoją prostotę i realną przydatność. Użytkownicy zaczęli zgłaszać wsparcie dla kolejnych menedżerów pakietów i platform, a lista obsługiwanych narzędzi rosła z każdą wersją.

Przejście do organizacji topgrade-rs

Po pewnym czasie oryginalny twórca zaczął mieć mniej czasu na aktywne rozwijanie projektu. Społeczność, nie chcąc dopuścić do porzucenia tak przydatnego narzędzia, przejęła jego utrzymanie. Repozytorium zostało przeniesione do organizacji topgrade-rs na GitHubie, gdzie jest aktywnie rozwijane przez zespół wolontariuszy z całego świata.

Informacja o forku

Aktualne repozytorium to topgrade-rs/topgrade – fork oryginalnego projektu r-darwish/topgrade, utrzymywany przez społeczność, aby zapewnić ciągłość projektu i regularne aktualizacje.

Topgrade dzisiaj (2025)

Na dzień dzisiejszy (maj 2025) Topgrade jest w wersji v17.0.0 (wydanej w marcu 2026), posiada ponad 3500 gwiazdek na GitHubie, 275 kontrybutorów i jest dostępny w oficjalnych repozytoriach wszystkich głównych dystrybucji Linuksa, Homebrew, Winget, AUR i wielu innych. Projekt posiada serwer Discord, aktywny system issues i PRs, a jego codebase to prawie w 100% kod Rust.

Topgrade obsługuje dziś dziesiątki platform i narzędzi, a jego konfiguracja przez plik TOML pozwala na bardzo szczegółowe dostosowanie działania do indywidualnych potrzeb każdego użytkownika.

Dlaczego Topgrade jest lepszy od zwykłej aktualizacji pakietów?

Wielu użytkowników zastanawia się: „Mam już alias w shellu, który uruchamia kilka komend – czemu miałbym używać osobnego narzędzia?”. To uczciwe pytanie, na które jest kilka bardzo konkretnych odpowiedzi.

Problem z ręczną aktualizacją pakietów

Tradycyjne podejście do aktualizacji systemu wygląda mniej więcej tak – użytkownik musi pamiętać o uruchomieniu wszystkich tych komend:

sudo apt update && sudo apt upgrade -y
brew update && brew upgrade && brew upgrade --cask
rustup update
cargo install-update -a
pip list --outdated | cut -d' ' -f1 | tail -n +3 | xargs pip install --upgrade
npm update -g
gem update
vim +PlugUpdate +qa
omz update
flatpak update -y
sudo snap refresh
sudo fwupdmgr refresh && sudo fwupdmgr update

To tylko część komend, które zaawansowany użytkownik może potrzebować uruchamiać regularnie. Problemy z tym podejściem są oczywiste:

Problem	Ręczna aktualizacja	Topgrade
Zapamiętywanie komend	Musisz pamiętać wszystkie komendy	Automatyczne wykrywanie
Nowe narzędzia	Musisz ręcznie dodać do aliasu	Automatycznie wykryte przy następnym uruchomieniu
Błędy i pomijanie kroków	Łatwo coś pominąć lub zapomnieć	Deterministyczna kolejność, nic nie zostaje pominięte
Przenośność między maszynami	Alias nie działa tak samo na każdym komputerze	Jeden plik config.toml, działa wszędzie
Obsługa błędów	Jeden błąd przerywa całą sekwencję	Kontynuuje, raportuje błędy na końcu
Czytelność wyjścia	Chaos różnych formatów outputu	Ujednolicony, kolorowy interfejs z sekcjami
Zdalne aktualizacje	Brak wsparcia	SSH remote execution wbudowany
Niestandardowe komendy	Wymaga modyfikacji aliasu	pre/post hooks w pliku konfiguracyjnym
Instalacja	Brak – to skrypt	Pojedynczy binarny plik wykonywalny

Inteligentne wykrywanie narzędzi

Topgrade nie aktualizuje „na ślepo” – przed uruchomieniem każdej komendy sprawdza, czy dane narzędzie jest zainstalowane w systemie. Jeśli nie masz zainstalowanego rustup, Topgrade nie będzie próbował go aktualizować i nie zgłosi błędu. Jeśli jutro zainstalujesz conda, kolejne uruchomienie topgrade automatycznie uwzględni ją w procesie aktualizacji – bez żadnej konfiguracji z twojej strony.

Resilient execution – odporność na błędy

To jest jeden z największych problemów z podejściem skryptowym. Kiedy jedna komenda w sekwencji zawiedzie (np. serwer APT jest chwilowo niedostępny), cały skrypt się zatrzymuje i nie aktualizuje pozostałych narzędzi. Topgrade działa inaczej – jeśli jedna sekcja zawiedzie, narzędzie kontynuuje pracę z następnymi, a na końcu prezentuje zbiorczy raport błędów.

---

Ważna uwaga

Topgrade nie jest narzędziem do zarządzania pakietami – nie pozwala instalować ani usuwać oprogramowania. To wyłącznie narzędzie do aktualizacji tego, co już masz zainstalowane.

---

Instalacja Topgrade – wszystkie platformy

Topgrade jest dostępny przez praktycznie każdy popularny menedżer pakietów. Poniżej znajdziesz instrukcje instalacji dla każdej platformy.

macOS (Homebrew)

brew install topgrade

Arch Linux (AUR)

yay -S topgrade-bin

Fedora/RHEL (Copr)

sudo dnf copr enable lilay/topgrade && sudo dnf install topgrade

Windows (Winget)

winget install topgrade-rs.topgrade

NixOS/Nix

nix-env -iA nixpkgs.topgrade

Void Linux

sudo xbps-install -S topgrade

macOS (MacPorts)

sudo port install topgrade

Python (pip/pipx)

pipx install topgrade

Rust (cargo)

cargo install topgrade

Instalacja Topgrade na Ubuntu – krok po kroku

Krok 1: Zaktualizuj system

Otwórz terminal i wpisz:

sudo apt update && sudo apt upgrade -y

Krok 2: Zainstaluj Rust (wymagane)

Topgrade instaluje się przez Cargo, więc potrzebujesz Rust:

sudo apt install curl build-essential -y

Następnie:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Gdy pojawi się zapytanie o opcjach instalacji, naciśnij enter (jest to wybór standardowej instalacji):

Po instalacji aktywuj Rust:

source $HOME/.cargo/env

Krok 3: Zainstaluj Topgrade przez Cargo

cargo install topgrade

To może potrwać kilka minut.

---

Samo-aktualizacja

Topgrade potrafi aktualizować samego siebie! Jeśli zainstalowałeś go przez cargo install, każde uruchomienie topgrade sprawdzi i zaktualizuje również sam siebie jako narzędzie cargo.

---

Podstawowe użycie i flagi CLI

Najprościej – uruchamiasz Topgrade bez żadnych argumentów i pozwalasz mu działać:

topgrade

Topgrade wyświetli listę wykrytych narzędzi, uruchomi aktualizację każdego z nich po kolei i podsumuje wyniki. Każda sekcja jest oddzielona wizualnie, a błędy są wyraźnie oznaczone.

Najważniejsze flagi i opcje

# Uruchom tylko wybrane kroki (np. tylko Homebrew i cargo)
topgrade --only brew,cargo

# Pomiń wybrane kroki
topgrade --disable pip,gem,npm

# Tryb dry-run – pokaż co zostałoby zaktualizowane, ale nie rób nic
topgrade --dry-run

# Nie pytaj o potwierdzenie (tryb nieinteraktywny, dobry do crona)
topgrade --yes
# lub
topgrade -y

# Pokaż szczegółowe logi
topgrade --verbose

# Pomiń aktualizację samego Topgrade
topgrade --no-self-upgrade

# Wymuś aktualizację nawet jeśli nie ma nowszych wersji
topgrade --force-intel

# Wyświetl pomoc z pełną listą flag
topgrade --help

Wyświetlanie listy dostępnych kroków

# Pokaż wszystkie kroki jakie Topgrade może wykonać
topgrade --list-steps

To bardzo przydatna komenda gdy chcesz zobaczyć dokładne nazwy kroków do użycia z flagami --only lub --disable.

Konfiguracja Topgrade – plik topgrade.toml

Topgrade przechowuje konfigurację w pliku topgrade.toml. Lokalizacja pliku zależy od systemu operacyjnego:

Linux/macOS: ~/.config/topgrade.toml lub ~/.config/topgrade/topgrade.toml

Windows: %APPDATA%\topgrade.toml lub %APPDATA%\topgrade\topgrade.toml

Przy pierwszym uruchomieniu Topgrade automatycznie tworzy plik konfiguracyjny z domyślnymi wartościami i komentarzami wyjaśniającymi każdą opcję.

Przykładowy plik konfiguracyjny

[misc]
# Nie pytaj o potwierdzenie przed każdym krokiem
assume_yes = true

# Pomiń kroki, które wymagają sudo
skip_sudo = false

# Wyczyść stare wersje pakietów po aktualizacji (np. brew cleanup)
cleanup = true

# Nie aktualizuj samego Topgrade
no_self_upgrade = false

[git]

# Katalogi repozytoriów Git do auto-pull repos = [ "~/projects/my-project", "~/dotfiles", "~/.config/nvim", ] # Opcje przekazywane do git pull arguments = "--rebase --autostash"

[linux]

# Pomiń aktualizacje Flatpak flatpak = false # Aktualizuj firmware przez fwupd firmware = true

[brew]

# Aktualizuj również aplikacje Cask cask = true # Uruchom brew cleanup po aktualizacji cleanup = true # Aktualizuj greedy (wersje beta, RC itp.) greedy_cask = false

[python]

# Aktualizuj pakiety pip w środowisku systemowym enable_pip_review = false

[composer]

# Ścieżka do globalnego composer.json self_update = true # Niestandardowe komendy uruchamiane PRZED aktualizacją

Niestandardowe komendy (custom commands)

Jedną z najpotężniejszych funkcji Topgrade jest możliwość definiowania własnych komend, które zostaną uruchomione przed lub po standardowych krokach aktualizacji. Możesz w ten sposób dodać dowolne narzędzie, którego Topgrade nie obsługuje natywnie:

[commands]
# Aktualizuj narzędzia zainstalowane przez mise/asdf
"mise upgrade" = "mise upgrade"

# Aktualizuj Neovim lazy.nvim
"Neovim Lazy" = "nvim --headless '+Lazy! sync' +qa"

# Aktualizuj konfigurację dotfiles
"dotfiles" = "cd ~/dotfiles && git pull --rebase"

# Aktualizuj narzędzia zainstalowane przez go install
"go tools" = "go install golang.org/x/tools/...@latest"

Przykłady użycia – realne scenariusze

Scenariusz 1: Programista fullstack na Ubuntu

Typowy programista fullstack ma zainstalowane: apt, cargo (narzędzia Rust), npm (globalne paczki), pip/pipx, Flatpak (aplikacje desktopowe) i wtyczki Neovim. Ręczna aktualizacja zajmuje 10-15 minut i wymaga zapamiętania co najmniej 8 różnych komend. Z Topgrade:

topgrade

Topgrade automatycznie wykryje apt, cargo, npm, pip, flatpak, fwupd oraz konfigurację Neovim i zaktualizuje wszystko w jednym kroku. Całość zajmuje tyle samo czasu, ale wymaga jednej komendy i zero uwagi z twojej strony.

Scenariusz 2: Użytkownik macOS z Homebrew

Na macOS Topgrade obsługuje brew update, brew upgrade, brew upgrade --cask, mas upgrade (App Store), aktualizacje Ruby gems, Python, npm, rustup i wiele więcej – wszystko za jednym zamachem:

# Zaktualizuj wszystko łącznie z aplikacjami Cask i App Store
topgrade

Scenariusz 3: Selektywna aktualizacja (tylko konkretne kroki)

Czasem chcesz zaktualizować tylko wybrane komponenty – na przykład gdy jesteś na wolnym łączu i chcesz pominąć duże pobierania:

# Zaktualizuj tylko narzędzia cargo i rustup
topgrade --only cargo,rustup

# Zaktualizuj wszystko oprócz systemu apt (np. gdy nie chcesz aktualizacji jądra)
topgrade --disable apt

# Zaktualizuj tylko menedżery pakietów (bez narzędzi deweloperskich)
topgrade --only apt,brew,flatpak,snap

Scenariusz 4: Aktualizacja repozytoriów Git (dotfiles)

Topgrade może automatycznie robić git pull na wybranych katalogach – doskonałe do synchronizowania dotfiles czy projektów:

[git]
repos = [
    "~/dotfiles",
    "~/.config/nvim",
    "~/projects/homelab-ansible",
]
arguments = "--rebase --autostash"

# Teraz topgrade automatycznie spulluje wszystkie wymienione repozytoria
topgrade

Scenariusz 5: Tryb nieinteraktywny dla skryptów

Gdy chcesz uruchomić Topgrade w skrypcie lub zadaniu cron bez żadnych interaktywnych pytań:

# Odpowiedz "tak" na wszystkie pytania automatycznie
topgrade --yes

# Połącz z verbose dla logowania
topgrade --yes --verbose 2>&1 | tee /var/log/topgrade.log

FAQ – Najczęstsze pytania o Topgrade

Czy Topgrade jest bezpieczny? Czy może zepsuć mój system?

Topgrade nie wykonuje żadnych działań, których nie wykonałbyś ręcznie – wywołuje dokładnie te same komendy, które uruchamiałbyś sam. Poziom ryzyka jest taki sam jak przy ręcznej aktualizacji. Dla systemów produkcyjnych zaleca się uruchamianie z flagą --dry-run przed faktyczną aktualizacją.

Czy mogę używać Topgrade na serwerze produkcyjnym?

Technicznie tak, ale wymaga to ostrożności. Na serwerach produkcyjnych zaleca się wyłączenie automatycznych aktualizacji systemu (--disable apt) i korzystanie z Topgrade tylko do aktualizacji narzędzi deweloperskich. Zawsze miej zaplanowany rollback przed aktualizacją.

Topgrade prosi o hasło sudo – czy to normalne?

Tak, to całkowicie normalne. Aktualizacje systemu (apt, pacman, dnf itp.) wymagają uprawnień administratora. Topgrade poprosi o hasło sudo tylko wtedy, gdy jest to rzeczywiście konieczne. Możesz skonfigurować sudo bez hasła dla konkretnych komend, jeśli chcesz w pełni zautomatyzować proces.

Jak pominąć konkretny krok, który zawsze kończy się błędem?

Użyj klucza disable w pliku konfiguracyjnym lub flagi --disable w wierszu poleceń: topgrade --disable pip3,gem. Możesz też trwale wyłączyć kroki w pliku topgrade.toml dodając [disable] steps = ["pip3", "gem"].

Czy Topgrade działa z Windows Subsystem for Linux (WSL)?

Tak! Topgrade działa zarówno natywnie na Windows (obsługując Winget, Scoop, Chocolatey), jak i wewnątrz WSL (gdzie obsługuje apt/pacman/dnf i inne narzędzia Linuksowe). Możesz zainstalować Topgrade w obu środowiskach niezależnie.

Jak dodać narzędzie, które Topgrade nie obsługuje natywnie?

Użyj sekcji [commands] w pliku konfiguracyjnym. Możesz zdefiniować dowolną komendę z dowolną nazwą, która zostanie uruchomiona jako część procesu aktualizacji: "Moje narzędzie" = "my-tool update".

Jaka jest różnica między topgrade-rs/topgrade a r-darwish/topgrade?

Oryginalne repozytorium r-darwish/topgrade zostało porzucone przez pierwotnego twórcę. Repozytorium topgrade-rs/topgrade to community fork, który jest aktywnie rozwijany i utrzymywany. Używaj wersji topgrade-rs – jest to oficjalna, aktualna wersja projektu.

Jak sprawdzić, które kroki Topgrade wykrył na moim systemie?

Uruchom topgrade --dry-run lub topgrade --list-steps. Topgrade pokaże listę wszystkich kroków, które zamierza wykonać bez faktycznego przeprowadzania aktualizacji.

Podsumowanie

Topgrade to jedno z tych narzędzi, które po kilku dniach użytkowania staje się absolutnie niezastąpione. Zamiast pamiętać o dziesiątkach komend, aliasach, które przestają działać po migracji na nowy system, i ręcznym śledzeniu co jest do zaktualizowania – uruchamiasz jedną komendę i wychodzisz na kawę.

Najważniejsze zalety Topgrade w pigułce: napisany w Rust gwarantuje szybkość i niezawodność; automatyczne wykrywanie narzędzi sprawia że działa od razu bez konfiguracji; wsparcie dla dziesiątek platform i menedżerów pakietów pokrywa praktycznie każdy możliwy setup; resilient execution nie zatrzymuje się przy pierwszym błędzie; plik konfiguracyjny TOML daje pełną kontrolę nad zachowaniem narzędzia; a wsparcie dla zdalnego wykonywania przez SSH pozwala zarządzać flotą maszyn z jednego miejsca.

Jeśli jeszcze nie masz Topgrade na swoim systemie, instalacja zajmuje dosłownie 30 sekund. W przypadku macOS: brew install topgrade. Na Arch Linux: yay -S topgrade-bin. Wszędzie indziej: cargo install topgrade. Po instalacji wystarczy raz uruchomić topgrade – narzędzie samo wykryje wszystko co masz i zaktualizuje to w jednym kroku.