Get Started

Upgrading topgrade

The precompiled binaries supplied in the Github releases page are compiled with a self upgrade feature. Topgrade will try to upgrade itself before attempting anything else and will respawn itself when an update is downloaded. If you choose to install Topgrade in this method it is recommended that you place the binary in some place which is writable by your user account, such as ~/.local/bin or %APPDATA%.

If you prefer to have Topgrade installed in system-wide manner then it's recommended to using OS package manager or cargo install.

Supported platforms

Topgrade should probably work on whichever platform it can be build. The real question is whether Topgrade knows that platform and can utilize its unique features, such as the operating system's package manager. Topgrade is tested on and knows the following platforms:

• Linux
  • Arch based
  • Red Hat based
  • Debian based
  • Clear Linux
  • Gentoo
  • NixOS
  • openSUSE
  • Void
• DragonFly BSD
• FreeBSD
• macOS
• Windows

DragonFly and Free BSD

Instalation

Either use cargo install or the compiled binaries from the release page. The compiled binaries contain a self-upgrading feature.

Currently, Topgrade requires Rust 1.65 or above. In general, Topgrade tracks the latest stable toolchain.

Usage

Just run topgrade.

Configuration

See config.example.toml for an example configuration file.

Configuration Path

${XDG_CONFIG_HOME:-~/.config}

topgrade will look for the configuration file in the following places, in order of priority:

1. CONFIG_DIR/topgrade.toml
2. CONFIG_DIR/topgrade/topgrade.toml

If the file with higher priority is present, no matter it is valid or not, the other configuration files will be ignored.

On the first run(no configuration file exists), topgrade will create a configuration file at CONFIG_DIR/topgrade.toml for you.

GNU/Linux

Installation

• Arch Linux: AUR
• NixOS: Nixpkgs
• Void Linux: XBPS

Other systems users can either use cargo install or the compiled binaries from the release page. The compiled binaries contain a self-upgrading feature.

Currently, Topgrade requires Rust 1.65 or above. In general, Topgrade tracks the latest stable toolchain.

Usage

Just run topgrade.

Configuration

See config.example.toml for an example configuration file.

Configuration Path

${XDG_CONFIG_HOME:-~/.config}

1. CONFIG_DIR/topgrade.toml
2. CONFIG_DIR/topgrade/topgrade.toml

If the file with higher priority is present, no matter it is valid or not, the other configuration files will be ignored.

On the first run(no configuration file exists), topgrade will create a configuration file at CONFIG_DIR/topgrade.toml for you.

macOS

Installation

Homebrew or MacPorts

Usage

Just run topgrade.

Configuration

See config.example.toml for an example configuration file.

Configuration Path

${XDG_CONFIG_HOME:-~/.config}

topgrade will look for the configuration file in the following places, in order of priority:

1. CONFIG_DIR/topgrade.toml
2. CONFIG_DIR/topgrade/topgrade.toml

If the file with higher priority is present, no matter it is valid or not, the other configuration files will be ignored.

On the first run(no configuration file exists), topgrade will create a configuration file at CONFIG_DIR/topgrade.toml for you.

Windows

• Scoop
• Winget

Usage

Just run topgrade.

Configuration

See config.example.toml for an example configuration file.

Configuration Path

%APPDATA%

topgrade will look for the configuration file in the following places, in order of priority:

1. CONFIG_DIR/topgrade.toml
2. CONFIG_DIR/topgrade/topgrade.toml

If the file with higher priority is present, no matter it is valid or not, the other configuration files will be ignored.

On the first run(no configuration file exists), topgrade will create a configuration file at CONFIG_DIR/topgrade.toml for you.

FAQ

It is important to note that Topgrade may be unable to upgrade certain applications used for launching it, including third-party terminals like cmder.

We suggest either creating a shortcut for 'topgrade--keep' or running Topgrade via your preferred shell.

Please note that if installed via scoop, Topgrade may fail to upgrade itself unless self_rename = true is set in topgrade.toml.

Notifications

Topgrades sends a desktop notification when a step has been failed. Desktop notifications works by default in macOS. On Linux, notify-send has to be installed in order for them to work.

Desktop notifications in other platforms is not supported at the moment.

If the configuration variable notify_each_step is set to true, Topgrade will send a desktop notification at the beginning of each step.