Runtime version manager in Termhint
Updated 19 November 2026All docs
Termhint includes a version manager for language runtimes. This page covers the supported tools, the termhint runtime commands, how a folder's version is chosen, where the files live, how every download is checked, and how to move over from nvm, pyenv, asdf and other managers. For an overview, see Runtimes. Xcode has its own page: Xcode versions and simulators.
Supported tools
| Tool | Name in commands | Source | Own version files |
|---|---|---|---|
| Node.js | node (also nodejs) |
nodejs.org | .nvmrc, .node-version |
| Go | go (also golang) |
go.dev | .go-version |
| Java | java |
Eclipse Temurin JDKs from Adoptium | .java-version |
| Python | python |
CPython from python-build-standalone | .python-version |
| Ruby | ruby |
Precompiled builds from jdx/ruby (Apple silicon) | .ruby-version |
| Bun | bun |
Bun's GitHub releases | .bun-version |
| Deno | deno |
dl.deno.land | .deno-version |
| Zig | zig |
ziglang.org | none |
| Erlang/OTP | erlang |
Precompiled builds from erlef/otp_builds | none |
| Elixir | elixir |
Elixir's GitHub releases | none |
| Gleam | gleam |
Gleam's GitHub releases | none |
| .NET SDK | dotnet (also dotnet-core) |
Microsoft | none |
| Dart SDK | dart |
Google's Dart archive | none |
| Julia | julia |
julialang.org | none |
| Xcode | xcode |
Apple (see Xcode) | .xcode-version |
Tools without their own version file are pinned with .tool-versions or the global default only. The other names in the second column (nodejs, golang, dotnet-core) are asdf's; they work in commands and in .tool-versions.
Termhint installs precompiled builds only. It never compiles a runtime and never runs an install script.
Note: Ruby builds exist for Apple silicon only. Elixir runs on an installed Erlang, so install Erlang first (
termhint runtime install erlang).
Install a version
termhint runtime install node # the newest Node release
termhint runtime install node lts # the newest long-term-support Node
termhint runtime install node 22 # the newest 22.x
termhint runtime install python 3.13 # the newest 3.13.x
termhint runtime install ruby@3.3.6 # tool and version in one word
The version can be:
latest(the default when you leave it out).- A full version (
22.11.0) or a partial one (22,3.3): the newest release that starts with it. - Node only:
lts(the newest long-term-support line) orlts-<name>/lts/<name>(lts-jod). - Pre-releases are picked only when you name them exactly (
24.0.0-rc.1).
A leading v is dropped (v22), and other managers' spellings work: ruby-3.3.6, temurin-21, and Elixir's 1.18.3-otp-27.
To see what you can install:
termhint runtime list-remote ruby # releases for this Mac
termhint runtime list-remote node --all # include pre-releases
The release list is kept for an hour. --refresh (on install and list-remote) asks the publisher again.
Elixir picks the precompiled build for the Erlang it will run on: the one your global default names, else the newest installed. If no Erlang is installed, or no build fits it, the install stops before anything is downloaded.
Choose a version
Pin a folder
termhint runtime use node 22 # this folder and the ones below it use Node 22
This writes the tool's line to .tool-versions in the current folder and keeps every other line as it was. A .tool-versions that is a symbolic link (or anything other than a regular file) is refused.
Set the default
termhint runtime use -g python 3.13 # Python 3.13 wherever nothing else is pinned
-g (or --global) writes the global defaults file, ~/.config/termhint/tool-versions. If that file is a symbolic link (for example from a dotfiles manager), the file it points to is updated.
The version does not have to be installed yet. When it is missing, the command prints the termhint runtime install line to run.
Use the system copy
termhint runtime use ruby system # the Ruby outside Termhint, in this folder
system means Termhint leaves the tool alone, so whatever is on your PATH (Homebrew, /usr/bin) runs.
How a version is chosen
For each tool, the first answer wins:
- The environment variable
TERMHINT_<TOOL>_VERSION, for exampleTERMHINT_NODE_VERSION=20. - Walking up from the current folder to
/, the nearest folder that has either a.tool-versionsline for the tool or one of the tool's own version files (see Supported tools). Within one folder,.tool-versionscomes first. - The global defaults in
~/.config/termhint/tool-versions.
With no answer at all, the version set as the default is used, if there is one.
Version files are read as data:
- From a tool's own file, only the first word of the first line that is not a comment. For
.xcode-version, the whole line. - From
.tool-versions, only the tool's line. If the tool appears twice, the later line wins. - Only regular files, and at most 4 KiB of each.
- A version may contain only letters, digits and
. _ + -, and no.., so a project cannot point outside Termhint's folder or make your shell run anything.
In .nvmrc, lts/* means lts, and node or stable mean latest.
Check what a folder uses
termhint runtime current # this folder
termhint runtime current ~/projects/api # another folder (its parents are searched too)
Each line shows the tool, the version asked for, the install folder (or not installed or system) and the file the version came from.
How switching works
There are no shims. On every prompt and every change of folder, Termhint's shell integration (zsh and bash) works out which version the folder asks for and puts that version's bin folder first on PATH. It also sets the variables some tools need:
| Tool | Variable |
|---|---|
| Go | GOROOT |
| Java | JAVA_HOME |
| Deno | DENO_INSTALL_ROOT (its .deno/bin is on PATH too) |
| .NET | DOTNET_ROOT |
| Xcode | DEVELOPER_DIR |
When the tool stops being active, the value from before comes back, unless something changed it meanwhile.
If a folder asks for a version that is not installed, the shell prints one line, once per folder, with the command to install it, and leaves that tool alone:
termhint: node 20 (from ~/projects/api/.nvmrc) is not installed — termhint runtime install node 20
Nothing is ever installed when you change folders.
To turn switching off in one shell, set TERMHINT_RUNTIMES_OFF=1. Editors and GUI apps that need a fixed path can use ~/.local/share/termhint/runtimes/<tool>/default, which points to your default version.
Scripts and cron jobs
Where no prompt runs, use exec. It puts the versions the current folder pins first on PATH, sets their variables and runs the command:
termhint runtime exec -- node --version
termhint runtime exec node@20 python@3.12 -- npm test
Versions named before -- win over the folder's pins. exec fails when a version it needs is not installed.
List and remove versions
termhint runtime list # every installed version; the default is marked (default)
termhint runtime list node # one tool
termhint runtime uninstall node 20.20.2
termhint runtime uninstall node 20 # works when only one 20.x is installed
When a partial version matches more than one installed version, uninstall lists them and asks you to name one.
A version folder you delete by hand drops out of termhint runtime list and Settings → Runtimes, and its record and links are removed.
Where runtimes live
| What | Where |
|---|---|
| Installed versions | ~/.local/share/termhint/runtimes/<tool>/<version> |
Version links (22, lts, latest, default) |
~/.local/share/termhint/runtimes/<tool>/ |
| Global defaults | ~/.config/termhint/tool-versions |
| Release lists and downloads | ~/.cache/termhint/runtimes |
TERMHINT_RUNTIMES moves the store to another folder. XDG_DATA_HOME, XDG_CONFIG_HOME and XDG_CACHE_HOME are honored when set.
Each install folder holds .termhint-install.json, a record of the download URL, its SHA-256 and what was checked. An install is unpacked and checked in a staging folder and only then renamed into place, so a version folder that exists is complete and verified.
Verification before install
Every download is checked before anything in it runs, and each check is anchored in the publisher, not only in the server that sent the file. A missing or wrong checksum, signature or attestation is a refusal, never a warning, and there is no switch to skip it. After the checks, the new binary runs once from its folder with an empty environment (only a minimal PATH) to confirm it works.
| Tool | Checks |
|---|---|
| Node.js | Hash in SHASUMS256.txt, which must carry a valid signature from a Node release key (built in) |
| Go | go.dev's published hashes, plus the files as logged in Google's checksum database (sum.golang.org, pinned key), plus Google's Developer ID signature on its programs |
| Java | Adoptium's SHA-256 plus a valid OpenPGP signature from the Adoptium release key (built in) |
| Python | Hash in the release's SHA256SUMS plus a GitHub artifact attestation from python-build-standalone's release workflow |
| Ruby | GitHub's recorded digest plus a GitHub artifact attestation from jdx/ruby's release workflow |
| Bun | Hash in SHASUMS256.txt plus a Developer ID signature from Bun's Apple team on every program |
| Deno | Published .sha256sum plus Deno Land's Developer ID signature |
| Zig | SHA-256 from Zig's index plus a minisign signature with Zig's key (pinned) |
| Erlang/OTP | Sigstore bundle made by erlef/otp_builds' release workflow |
| Elixir | Published .sha256sum plus a GitHub artifact attestation from Elixir's release workflow |
| Gleam | Published .sha256 plus a Sigstore bundle made by Gleam's release workflow |
| .NET SDK | SHA-512 from Microsoft's release files, which must carry a valid Microsoft signature (pinned DigiCert root), plus Microsoft's Developer ID signature on the programs |
| Dart SDK | Published .sha256sum plus a Developer ID signature from Google or FLUTTER.IO on every program |
| Julia | SHA-256 from Julia's version list plus a GPG signature by Julia's current release key (built in) |
| Xcode | Apple's signature on the .xip and on the app (see Xcode) |
Releases that cannot pass these checks are not listed: Elixir only the 1.18 line, Bun from 1.0.24 (a few later ones are left out too), Deno from 1.38.1, Gleam from 1.10.0, Dart x64 from 2.5.0, and Julia only versions signed by its current key. A Temurin build without a published signature (before mid-2022) is refused.
The release index
For Bun, Elixir, Erlang, Gleam, Python and Ruby, Termhint first reads the list of releases from index.termhint.com, rebuilt every hour. Their own listings go through GitHub, whose API allows 60 requests an hour without a token. The list counts only when it carries a Sigstore bundle made by Termhint's index workflow, is less than a week old and is not older than the list seen before. Otherwise, and with --refresh, the publisher's own listing is used.
Only the list comes from the index. The checksums, signatures and attestations are always fetched from the publisher at install time.
A GITHUB_TOKEN in your environment raises GitHub's limit for listings that go to GitHub. It is sent only to https://api.github.com.
If an install is refused, see Troubleshooting.
Move from nvm, pyenv, asdf and others
termhint runtime migrate takes over the versions of other version managers:
termhint runtime migrate --dry-run # what would move and which shell lines would be turned off
termhint runtime migrate nvm pyenv # take over the named managers
termhint runtime migrate # take over every manager found
termhint runtime migrate --undo # turn their shell lines back on
termhint runtime migrate --remove nvm # also uninstall nvm and move its folders to the Trash
Managers it knows: nvm, fnm, volta, nodenv, rvm, rbenv, chruby, pyenv, goenv, jenv, sdkman, asdf, mise, bun (Bun's installer), deno (Deno's installer) and xcodes.
For each manager, migrate:
- Installs its versions with Termhint. An Xcode already in
/Applicationsis kept where it is. - Makes the manager's defaults your Termhint defaults.
- Reinstalls each version's global npm packages, gems with commands and pip tools into the matching Termhint version. Packages added with
npm linkare listed, not moved. - Turns off the manager's lines in
~/.zshrc,~/.zprofile,~/.bash_profile,~/.bashrcand~/.profile. Each file is backed up first, and each line gets#termhint-off#in front.
A manager whose default version does not install stays on. Versions of tools Termhint does not manage (asdf's terraform, SDKMAN's gradle) are listed and stay with the manager. Bun's and Deno's installers keep their shell lines, because their bin folder holds the commands you installed with bun add -g or deno install -g.
| Flag | Effect |
|---|---|
--dry-run |
Print the plan only |
--undo |
Turn the lines Termhint turned off back on, byte for byte, for managers still installed. Takes no manager name and no --remove |
--remove |
Also brew uninstall the manager (when Homebrew installed it) and move its folders to the Trash, but only once every version installed and every global package moved |
Settings → Runtimes → Other Managers does the same with Replace with Termhint…. More on each manager: nvm alternative, pyenv alternative, asdf alternative.
Command reference
| Command | What it does |
|---|---|
termhint runtime install <tool> [<version>] [--refresh] |
Download, verify and install a version |
termhint runtime uninstall <tool> <version> |
Remove an installed version |
termhint runtime list [<tool>] |
Installed versions |
termhint runtime list-remote <tool> [--all] [--refresh] |
Versions the publisher offers for this Mac |
termhint runtime use [-g] <tool> [<version>] |
Pin a version in this folder, or as the default with -g |
termhint runtime current [<dir>] |
What a folder asks for, and whether it is installed |
termhint runtime exec [<tool>@<version>…] -- <command> |
Run a command with the folder's versions first on PATH |
termhint runtime migrate [--dry-run] [--undo] [--remove] [<manager>…] |
Take over other version managers |
Each command prints its own help with --help. Xcode's commands are on Xcode versions and simulators; every other command is in the CLI reference.