Polyglot runtime manager (asdf rust clone)
The following shows using rtx to install nodejs and
jq into a project using a .tool-versions
file.
hyperfine is used to show the performance using
rtx vs asdf. (See Performance).
Note that calling which node
gives us a real path to the binary, not a shim.
- asdf-compatible - rtx is compatible with asdf plugins and
.tool-versions
files. It can be used as a drop-in replacement. - Polyglot - compatible with any language, so no more figuring out how nvm, nodenv, pyenv, etc work individually—just use 1 tool.
- Fast - rtx is written in Rust and is very fast. 20x-200x faster than asdf.
- No shims - shims (used by asdf) cause problems, they break
which node
, and add overhead. We don't use them by default. - Better UX - asdf is full of strange UX decisions (like
asdf plugin add
but alsoasdf install
). We've taken care to make rtx easy to use. - Fuzzy matching and aliases - no need to specify exact version numbers like with asdf.
- One command install - No need to manually install each plugin, just run
rtx install
and it will install all the plugins you need.
Install rtx (other methods here):
$ curl https://rtx.pub/rtx-latest-macos-arm64 > ~/bin/rtx
$ chmod +x ~/bin/rtx
$ rtx --version
rtx 1.18.1
Hook rtx into to your shell. This will automatically add ~/bin
to PATH
if it isn't already.
(choose one, and open a new shell session for the changes to take effect):
$ echo 'eval "$(~/bin/rtx activate bash)"' >> ~/.bashrc
$ echo 'eval "$(~/bin/rtx activate zsh)"' >> ~/.zshrc
$ echo '~/bin/rtx activate fish | source' >> ~/.config/fish/config.fish
Warning
If you use direnv, you will want to activate direnv before rtx. There is also an alternative way to use rtx inside of direnv, see here.
Install a runtime and set it as the default:
$ rtx install nodejs@18
$ rtx global nodejs@18
$ node -v
v18.10.9
Note
rtx install
is optional,rtx global
will prompt to install the runtime if it's not already installed. This is configurable in~/.config/rtx/config.toml
.
- About
- Installation
- Other Shells
- Uninstalling
- Configuration
- .tool-versions
- Legacy version files
- Global config: ~/.config/rtx/config.toml
- Environment variables
- RTX_MISSING_RUNTIME_BEHAVIOR
- RTX_DATA_DIR
- RTX_CACHE_DIR
- RTX_CONFIG_FILE
- RTX_DEFAULT_TOOL_VERSIONS_FILENAME
- RTX_${PLUGIN}_VERSION
- RTX_LEGACY_VERSION_FILE
- RTX_LOG_LEVEL=trace|debug|info|warn|error
- RTX_LOG_FILE=~/.rtx/rtx.log
- RTX_LOG_FILE_LEVEL=trace|debug|info|warn|error
- RTX_VERBOSE=1
- RTX_ASDF_COMPAT=1
- RTX_JOBS=1
- RTX_SHORTHANDS_FILE=~/.config/rtx/shorthands.toml
- RTX_DISABLE_DEFAULT_SHORTHANDS=1
- RTX_HIDE_OUTDATED_BUILD=1
- Aliases
- Plugins
- FAQs
- Commands
- rtx activate
- rtx alias get
- rtx alias ls
- rtx alias set
- rtx alias unset
- rtx bin-paths
- rtx cache clear
- rtx complete
- rtx current
- rtx deactivate
- rtx direnv activate
- rtx doctor
- rtx env
- rtx exec
- rtx global
- rtx implode
- rtx install
- rtx latest
- rtx local
- rtx ls
- rtx ls-remote
- rtx plugins install
- rtx plugins ls
- rtx plugins ls-remote
- rtx plugins uninstall
- rtx plugins update
- rtx reshim
- rtx self-update
- rtx settings get
- rtx settings ls
- rtx settings set
- rtx settings unset
- rtx shell
- rtx uninstall
- rtx version
- rtx where
- rtx which
- Comparison to asdf
- Shims
- direnv
- Cache Behavior
- Development
rtx is a tool for managing programming language and tool versions. For example, use this to install
a particular version of node.js and ruby for a project. Using rtx activate
, you can have your
shell automatically switch to the correct node and ruby versions when you cd
into the project's
directory. Other projects on your machine can use a different set of versions.
rtx is inspired by asdf and uses asdf's vast plugin ecosystem under the hood. However, it is much faster than asdf and has a more friendly user experience. For more on how rtx compares to asdf, see below. The goal of this project was to create a better front-end to asdf.
It uses the same .tool-versions
file that asdf uses. It's also compatible with idiomatic version
files like .node-version
and .ruby-version
. See Legacy Version Files below.
Come chat about rtx on discord.
rtx installs as a shell extension (e.g. rtx activate zsh
) that sets the PATH
environment variable to point your shell to the correct runtime binaries. When you cd
into a
directory containing a .tool-versions
file, rtx will automatically activate the correct versions.
Every time your prompt starts it will call rtx hook-env
to fetch new environment variables. This
should be very fast and it exits early if the the directory wasn't changed or the .tool-versions
files haven't been updated. On my machine this takes 4ms in the fast case, 14ms in the slow case. See Performance for more on this topic.
Unlike asdf which uses shim files to dynamically locate runtimes when they're called, rtx modifies
PATH
ahead of time so the runtimes are called directly. This is not only faster since it avoids
any overhead, but it also makes it so commands like which node
work as expected. This also
means there isn't any need to run asdf reshim
after installing new runtime binaries.
rtx does not directly install runtimes. Instead, it uses asdf plugins to install runtimes. See plugins below.
rtx install [email protected] Install a specific version number
rtx install [email protected] Install a fuzzy version number
rtx local nodejs@18 Use node-18.x in current project
rtx global nodejs@18 Use node-18.x as default
rtx install nodejs Install the version specified in .tool-versions
rtx local nodejs@latest Use latest node in current directory
rtx global nodejs@system Use system node as default
rtx x nodejs@18 -- node app.js Run `node app.js` with the PATH pointing to node-18.x
Note that it isn't necessary for rtx
to be on PATH
. If you run the activate script in your rc
file, rtx will automatically add itself to PATH
.
$ curl https://rtx.pub/install.sh | sh
or if you're allergic to | sh
:
$ curl https://rtx.pub/rtx-latest-macos-arm64 > /usr/local/bin/rtx
It doesn't matter where you put it. So use ~/bin
, /usr/local/bin
, ~/.local/share/rtx/bin/rtx
or whatever.
Supported architectures:
x64
arm64
Supported platforms:
macos
linux
If you need something else, compile it with cargo.
There are 2 ways to install rtx with Homebrew. The recommended method is to use the custom tap which will always contain the latest release.
$ brew install jdxcode/tap/rtx
Alternatively, you can use the built-in tap (homebrew-core), which will be updated once Homebrew maintainers merge the PR for a new release:
$ brew install rtx
Build from source with Cargo:
$ cargo install rtx-cli
Do it faster with [cargo-binstall](https://github.com/cargo-bins/cargo-binstall):
```sh-session
$ cargo install cargo-binstall
$ cargo binstall rtx-cli
Build from the latest commit in main:
$ cargo install rtx-cli --git https://github.com/jdxcode/rtx --branch main
rtx is available on npm as precompiled binaries. This isn't a node.js package, just distributed
via npm. It can be useful for JS projects that want to setup rtx via package.json
or npx
.
$ npm install -g @jdxcode/rtx
Or use npx if you just want to test it out for a single command without fully installing:
$ npx @jdxcode/rtx exec [email protected] -- python some_script.py
Download the latest release from GitHub.
$ curl https://github.com/jdxcode/rtx/releases/download/v1.18.1/rtx-v1.18.1-linux-x64 | tar -xJv
$ mv rtx/bin/rtx /usr/local/bin
For installation on Ubuntu/Debian:
wget -qO - https://rtx.pub/gpg-key.pub | gpg --dearmor | sudo tee /usr/share/keyrings/rtx-archive-keyring.gpg 1> /dev/null
echo "deb [signed-by=/usr/share/keyrings/rtx-archive-keyring.gpg arch=amd64] https://rtx.pub/deb stable main" | sudo tee /etc/apt/sources.list.d/rtx.list
sudo apt update
sudo apt install -y rtx
Warning
If you're on arm64 you'll need to run the following:
echo "deb [signed-by=/usr/share/keyrings/rtx-archive-keyring.gpg arch=arm64] https://rtx.pub/deb stable main" | sudo tee /etc/apt/sources.list.d/rtx.list
For Fedora, CentOS, Amazon Linux, RHEL and other dnf-based distributions:
dnf install -y dnf-plugins-core
dnf config-manager --add-repo https://rtx.pub/rpm/rtx.repo
dnf install -y rtx
yum install -y yum-utils
yum-config-manager --add-repo https://rtx.pub/rpm/rtx.repo
yum install -y rtx
For Alpine Linux:
apk add rtx --repository=http://dl-cdn.alpinelinux.org/alpine/edge/testing/
For Arch Linux:
git clone https://aur.archlinux.org/rtx.git
cd rtx
makepkg -si
$ echo 'eval "$(rtx activate bash)"' >> ~/.bashrc
$ echo 'rtx activate fish | source' >> ~/.config/fish/config.fish
Since .xsh
files are not compiled you may shave a bit off startup time by using a pure Python import: add the code below to, for example, ~/.config/xonsh/rtx.py
config file and import rtx
it in ~/.config/xonsh/rc.xsh
:
from pathlib import Path
from xonsh.built_ins import XSH
ctx = XSH.ctx
rtx_init = subprocess.run([Path('~/bin/rtx').expanduser(),'activate','xonsh'],capture_output=True,encoding="UTF-8").stdout
XSH.builtins.execx(rtx_init,'exec',ctx,filename='rtx')
Or continue to use rc.xsh
/.xonshrc
:
echo 'execx($(~/bin/rtx activate xonsh))' >> ~/.config/xonsh/rc.xsh # or ~/.xonshrc
Given that rtx
replaces both shell env $PATH
and OS environ PATH
, watch out that your configs don't have these two set differently (might throw os.environ['PATH'] = xonsh.built_ins.XSH.env.get_detyped('PATH')
at the end of a config to make sure they match)
Adding a new shell is not hard at all since very little shell code is in this project. See here for how the others are implemented. If your shell isn't currently supported I'd be happy to help you get yours integrated.
Use rtx implode
to uninstall rtx. This will remove the rtx binary and all of its data. Use
rtx implode --help
for more information.
Alternatively, manually remove the following directories to fully clean up:
~/.local/share/rtx
(can also beRTX_DATA_DIR
orXDG_DATA_HOME/rtx
)~/.config/rtx
(can also beRTX_CONFIG_DIR
orXDG_CONFIG_HOME/rtx
)- on Linux:
~/.cache/rtx
(can also beRTX_CACHE_DIR
orXDG_CACHE_HOME/rtx
) - on macOS:
~/Library/Caches/rtx
(can also beRTX_CACHE_DIR
)
The .tool-versions
file is used to specify the runtime versions for a project. An example of this
is:
nodejs 18.0.0 # comments are allowed
ruby 3 # can be fuzzy version
shellcheck latest # also supports "latest"
jq 1.6
erlang ref:master # compile from vcs ref
golang prefix:1.19 # uses the latest 1.19.x version—needed in case "1.19" is an exact match
shfmt path:./shfmt # use a custom runtime
Create .tool-versions
files manually, or use rtx local
to create them automatically.
See the asdf docs for more info on this file format.
rtx supports "legacy version files" just like asdf. They're language-specific files like .node-version
and .python-version
. These are ideal for setting the runtime version of a project without forcing
other developers to use a specific tool like rtx/asdf.
They support aliases, which means you can have an .nvmrc
file with lts/hydrogen
and it will work
in rtx and nvm. Here are some of the supported legacy version files:
Plugin | "Legacy" (Idiomatic) Files |
---|---|
crystal | .crystal-version |
elixir | .exenv-version |
golang | .go-version , go.mod |
java | .java-version |
nodejs | .nvmrc , .node-version |
python | .python-version |
ruby | .ruby-version , Gemfile |
terraform | .terraform-version , .packer-version , main.tf |
yarn | .yvmrc |
In rtx these are enabled by default. You can disable them with rtx settings set legacy_version_file false
.
There is a performance cost to having these when they're parsed as it's performed by the plugin in
bin/parse-version-file
. However these are cached so it's not a huge deal.
You may not even notice.
Note
asdf calls these "legacy version files" so we do too. I think this is a bad name since it implies that they shouldn't be used—which is definitely not the case IMO. I prefer the term "idiomatic" version files since they're version files not specific to asdf/rtx and can be used by other tools. (
.nvmrc
being a notable exception, which is tied to a specific tool.)
rtx can be configured in ~/.config/rtx/config.toml
. The following options are available (defaults shown):
# whether to prompt to install plugins and runtimes if they're not already installed
missing_runtime_behavior = 'prompt' # other options: 'ignore', 'warn', 'prompt', 'autoinstall'
# plugins can read the versions files used by other version managers (if enabled by the plugin)
# for example, .nvmrc in the case of nodejs's nvm
legacy_version_file = true # enabled by default (different than asdf)
# configure `rtx install` to always keep the downloaded archive
always_keep_download = false # deleted after install by default
# configure how frequently (in minutes) to fetch updated plugin repository changes
# this is updated whenever a new runtime is installed
# (note: this isn't currently implemented but there are plans to add it: https://github.com/jdxcode/rtx/issues/128)
plugin_autoupdate_last_check_duration = 10080 # (one week) set to 0 to disable updates
verbose = false # set to true to see full installation output, see `RTX_VERBOSE`
asdf_compat = false # set to true to ensure .tool-versions will be compatible with asdf, see `RTX_ASDF_COMPAT`
jobs = 4 # number of plugins or runtimes to install in parallel. The default is `4`.
shorthands_file = '~/.config/rtx/shorthands.toml' # path to the shorthands file, see `RTX_SHORTHANDS_FILE`
disable_default_shorthands = false # disable the default shorthands, see `RTX_DISABLE_DEFAULT_SHORTHANDS`
[alias.nodejs]
my_custom_node = '18' # makes `rtx install nodejs@my_custom_node` install node-18.x
# this can also be specified in a plugin (see below in "Aliases")
These settings can also be managed with rtx settings ls|get|set|unset
.
rtx can also be configured via environment variables. The following options are available:
This is the same as the missing_runtime_behavior
config option in ~/.config/rtx/config.toml
.
$ RTX_MISSING_RUNTIME_BEHAVIOR=ignore rtx install nodejs@18
$ RTX_NODEJS_VERSION=18 rtx exec -- node --version
This is the directory where rtx stores its data. The default is ~/.local/share/rtx
.
This is the directory where rtx stores cache. The default is ~/.cache/rtx
on Linux and ~/Library/Caches/rtx
on macOS.
This is the path to the config file. The default is ~/.config/rtx/config.toml
.
(Or $XDG_CONFIG_HOME/config.toml
if that is set)
Set to something other than ".tool-versions" to have rtx look for configuration with alternate names.
Set the version for a runtime. For example, RTX_NODEJS_VERSION=18
will use [email protected] regardless
of what is set in .tool-versions
.
Plugins can read the versions files used by other version managers (if enabled by the plugin) for example, .nvmrc in the case of nodejs's nvm.
Can also use RTX_DEBUG=1
, RTX_TRACE=1
, and RTX_QUIET=1
. These adjust the log
output to the screen.
Output logs to a file.
Same as RTX_LOG_LEVEL
but for the log file output level. This is useful if you want
to store the logs but not have them litter your display.
This shows the installation output during rtx install
and rtx plugin install
.
This should likely be merged so it behaves the same as RTX_DEBUG=1
and we don't have
2 configuration for the same thing, but for now it is it's own config.
Only output .tool-versions
files in rtx local|global
which will be usable by asdf.
Set the number plugins or runtimes to install in parallel. The default is 4
.
Use a custom file for the shorthand aliases. This is useful if you want to share plugins within an organization.
The file should be in toml format:
elixir = "https://github.com/my-org/rtx-elixir.git"
nodejs = "https://github.com/my-org/rtx-nodejs.git"
Disables the shorthand aliases for installing plugins. You will have to specify full urls when
installing plugins, e.g.: rtx plugin install nodejs https://github.com/asdf-vm/asdf-nodejs.git
Currently this disables the following:
--fuzzy
as default behavior (rtx local nodejs@18
will save exact version)
If a release is 12 months old, it will show a warning message every time it launches:
rtx has not been updated in over a year. Please update to the latest version.
You likely do not want to be using rtx if it is that old. I'm doing this instead of
autoupdating. If, for some reason, you want to stay on some old version, you can hide
this message with RTX_HIDE_OUTDATED_BUILD=1
.
rtx supports aliasing the versions of runtimes. One use-case for this is to define aliases for LTS
versions of runtimes. For example, you may want to specify lts/hydrogen
as the version for [email protected].
So you can use the runtime with nodejs lts/hydrogen
in .tool-versions
.
User aliases can be created by adding an alias.<PLUGIN>
section to ~/.config/rtx/config.toml
:
[alias.nodejs]
my_custom_18 = '18'
Plugins can also provide aliases via a bin/list-aliases
script. Here is an example showing node.js
versions:
#!/usr/bin/env bash
echo "lts/hydrogen 18"
echo "lts/gallium 16"
echo "lts/fermium 14"
Note:
Because this is rtx-specific functionality not currently used by asdf it isn't likely to be in any plugin currently, but plugin authors can add this script without impacting asdf users.
rtx uses asdf's plugin ecosystem under the hood. These plugins contain shell scripts like
bin/install
(for installing) and bin/list-all
(for listing all of the available versions).
See https://github.com/asdf-vm/asdf-plugins for the list of built-in plugins shorthands. See asdf's Create a Plugin for how to create your own or just learn more about how they work.
You can make git ignore these files in 3 different ways:
- Adding
.tool-versions
to project's.gitignore
file. This has the downside that you need to commit the change to the ignore file. - Adding
.tool-versions
to project's.git/info/exclude
. This file is local to your project so there is no need to commit it. - Adding
.tool-versions
to global gitignore (core.excludesFile
). This will cause git to ignore.tool-versions
files in all projects. You can explicitly add one to a project if needed withgit add --force .tool-versions
.
Just follow the asdf docs. Everything should work the same. If it isn't, please open an issue.
First try setting RTX_LOG_LEVEL=debug
or RTX_LOG_LEVEL=trace
and see if that gives you more information.
You can also set RTX_LOG_FILE=/path/to/logfile
to write the logs to a file.
If something is happening with the activate hook, you can try disabling it and calling eval "$(rtx hook-env)"
manually.
It can also be helpful to use rtx env
to see what environment variables it wants to use.
Lastly, there is an rtx doctor
command. It doesn't have much in it but I hope to add more functionality
to that to help debug issues.
This is something we'd like to add! jdx#66
It's not a near-term goal and it would require plugin modifications, but it should be feasible.
Enables rtx to automatically modify runtimes when changing directory
This should go into your shell's rc file.
Otherwise, it will only take effect in the current session.
(e.g. ~/.bashrc)
Usage: activate [OPTIONS] [SHELL_TYPE]
Arguments:
[SHELL_TYPE]
Shell type to generate the script for
[possible values: bash, fish, xonsh, zsh]
Options:
--status
Show "rtx: <PLUGIN>@<VERSION>" message when changing directories
Examples:
$ eval "$(rtx activate bash)"
$ eval "$(rtx activate zsh)"
$ rtx activate fish | source
$ execx($(rtx activate xonsh))
Show an alias for a plugin
This is the contents of an alias.<PLUGIN> entry in ~/.config/rtx/config.toml
Usage: get <PLUGIN> <ALIAS>
Arguments:
<PLUGIN>
The plugin to show the alias for
<ALIAS>
The alias to show
Examples:
$ rtx alias get nodejs lts/hydrogen
18.0.0
List aliases
Shows the aliases that can be specified.
These can come from user config or from plugins in `bin/list-aliases`.
For user config, aliases are defined like the following in `~/.config/rtx/config.toml`:
[alias.nodejs]
lts = "18.0.0"
Usage: ls [OPTIONS]
Options:
-p, --plugin <PLUGIN>
Show aliases for <PLUGIN>
Examples:
$ rtx aliases
nodejs lts/hydrogen 18.0.0
Add/update an alias for a plugin
This modifies the contents of ~/.config/rtx/config.toml
Usage: set <PLUGIN> <ALIAS> <VALUE>
Arguments:
<PLUGIN>
The plugin to set the alias for
<ALIAS>
The alias to set
<VALUE>
The value to set the alias to
Examples:
$ rtx alias set nodejs lts/hydrogen 18.0.0
Clears an alias for a plugin
This modifies the contents of ~/.config/rtx/config.toml
Usage: unset <PLUGIN> <ALIAS>
Arguments:
<PLUGIN>
The plugin to remove the alias from
<ALIAS>
The alias to remove
Examples:
$ rtx alias unset nodejs lts/hydrogen
List all the active runtime bin paths
Usage: bin-paths
Deletes all cache files in rtx
Usage: clear
Generate shell completions
Usage: complete --shell <SHELL>
Options:
-s, --shell <SHELL>
shell type
[possible values: bash, elvish, fish, powershell, zsh]
Examples:
$ rtx complete -s bash > /etc/bash_completion.d/rtx
$ rtx complete -s zsh > /usr/local/share/zsh/site-functions/_rtx
$ rtx complete -s fish > ~/.config/fish/completions/rtx.fish
Shows current active and installed runtime versions
This is similar to `rtx ls --current`, but this only shows the runtime
and/or version. It's designed to fit into scripts more easily.
Usage: current [PLUGIN]
Arguments:
[PLUGIN]
Plugin to show versions of
e.g.: ruby, nodejs
Examples:
# outputs `.tool-versions` compatible format
$ rtx current
python 3.11.0 3.10.0
shfmt 3.6.0
shellcheck 0.9.0
nodejs 18.13.0
$ rtx current nodejs
18.13.0
# can output multiple versions
$ rtx current python
3.11.0 3.10.0
Disable rtx for current shell session
This can be used to temporarily disable rtx in a shell session.
Usage: deactivate
Examples:
$ rtx deactivate bash
$ rtx deactivate zsh
$ rtx deactivate fish
$ execx($(rtx deactivate xonsh))
Output direnv function to use rtx inside direnv
See https://github.com/jdxcode/rtx#direnv for more information
Because this generates the legacy files based on currently installed plugins,
you should run this command after installing new plugins. Otherwise
direnv may not know to update environment variables when legacy file versions change.
Usage: activate
Examples:
$ rtx direnv activate > ~/.config/direnv/lib/use_rtx.sh
$ echo 'use rtx' > .envrc
$ direnv allow
Check rtx installation for possible problems.
Usage: doctor
Examples:
$ rtx doctor
[WARN] plugin nodejs is not installed
exports env vars to activate rtx in a single shell session
Use this if you don't want to permanently install rtx. It's not necessary to
use this if you have `rtx activate` in your shell rc file.
This can be used similarly to `asdf shell`. It requires `eval` to work since
it's not written in Bash.
It's also useful just to see what environment variables rtx sets.
Usage: env [OPTIONS] [RUNTIME]...
Arguments:
[RUNTIME]...
Runtime version to use
Options:
-s, --shell <SHELL>
Shell type to generate environment variables for
[possible values: bash, fish, xonsh, zsh]
Examples:
$ eval "$(rtx env -s bash)"
$ eval "$(rtx env -s zsh)"
$ rtx env -s fish | source
$ execx($(rtx env -s xonsh))
Execute a command with runtime(s) set
use this to avoid modifying the shell session or running ad-hoc commands with the rtx runtimes
set.
Runtimes will be loaded from .tool-versions, though they can be overridden with <RUNTIME> args
Note that only the plugin specified will be overridden, so if a `.tool-versions` file
includes "nodejs 18" but you run `rtx exec [email protected]`; it will still load nodejs@18.
The "--" separates runtimes from the commands to pass along to the subprocess.
Usage: exec [OPTIONS] [RUNTIME]... [-- <COMMAND>...]
Arguments:
[RUNTIME]...
Runtime(s) to start
e.g.: nodejs@18 [email protected]
[COMMAND]...
Command string to execute (same as --command)
Options:
-c, --command <C>
Command string to execute
Examples:
rtx exec nodejs@18 -- node ./app.js # launch app.js using node-18.x
rtx x nodejs@18 -- node ./app.js # shorter alias
# Specify command as a string:
rtx exec nodejs@18 [email protected] --command "node -v && python -V"
Sets global .tool-versions to include a specified runtime
Displays the contents of ~/.tool-versions after writing.
The file is `$HOME/.tool-versions` by default.
Use `rtx local` to set a runtime version locally in the current directory.
Usage: global [OPTIONS] [RUNTIME]...
Arguments:
[RUNTIME]...
Runtime(s) to add to .tool-versions
e.g.: nodejs@18
If this is a single runtime with no version, the current value of the global
.tool-versions will be displayed
Options:
--pin
Save exact version to `~/.tool-versions`
e.g.: `rtx local --pin nodejs@18` will save `nodejs 18.0.0` to ~/.tool-versions
--fuzzy
Save fuzzy version to `~/.tool-versions`
e.g.: `rtx local --fuzzy nodejs@18` will save `nodejs 18` to ~/.tool-versions this is the default behavior unless RTX_ASDF_COMPAT=1
--remove <PLUGIN>
Remove the plugin(s) from ~/.tool-versions
Examples:
# set the current version of nodejs to 18.x
# will use a fuzzy version (e.g.: 18) in .tool-versions file
$ rtx global --fuzzy nodejs@18
# set the current version of nodejs to 18.x
# will use a precise version (e.g.: 18.0.0) in .tool-versions file
$ rtx global --pin nodejs@18
# show the current version of nodejs in ~/.tool-versions
$ rtx global nodejs
18.0.0
Removes rtx CLI and all generated data
Skips config directory by default.
Usage: implode [OPTIONS]
Options:
--config
Also remove config directory
--dry-run
List directories that would be removed without actually removing them
Install a runtime
This will install a runtime to `~/.local/share/rtx/installs/<PLUGIN>/<VERSION>`
It won't be used simply by being installed, however.
For that, you must set up a `.tool-version` file manually or with `rtx local/global`.
Or you can call a runtime explicitly with `rtx exec <PLUGIN>@<VERSION> -- <COMMAND>`.
Runtimes will be installed in parallel. To disable, set `--jobs=1` or `RTX_JOBS=1`
Usage: install [OPTIONS] [RUNTIME]...
Arguments:
[RUNTIME]...
Runtime(s) to install
e.g.: nodejs@18
Options:
-p, --plugin <PLUGIN>
Only install runtime(s) for <PLUGIN>
-f, --force
Force reinstall even if already installed
-v, --verbose...
Show installation output
Examples:
$ rtx install [email protected] # install specific nodejs version
$ rtx install nodejs@18 # install fuzzy nodejs version
$ rtx install nodejs # install version specified in .tool-versions
$ rtx install # installs all runtimes specified in .tool-versions for installed plugins
$ rtx install --all # installs all runtimes and all plugins
Get the latest runtime version of a plugin's runtimes
Usage: latest <RUNTIME>
Arguments:
<RUNTIME>
Runtime to get the latest version of
Examples:
$ rtx latest nodejs@18 # get the latest version of nodejs 18
18.0.0
$ rtx latest nodejs # get the latest stable version of nodejs
20.0.0
Sets .tool-versions to include a specific runtime
then displays the contents of .tool-versions
use this to set the runtime version when within a directory
use `rtx global` to set a runtime version globally
Usage: local [OPTIONS] [RUNTIME]...
Arguments:
[RUNTIME]...
Runtimes to add to .tool-versions
e.g.: nodejs@18
if this is a single runtime with no version,
the current value of .tool-versions will be displayed
Options:
-p, --parent
Recurse up to find a .tool-versions file rather than using the current directory only
by default this command will only set the runtime in the current directory ("$PWD/.tool-versions")
--pin
Save exact version to `.tool-versions`
e.g.: `rtx local --pin nodejs@18` will save `nodejs 18.0.0` to .tool-versions
--fuzzy
Save fuzzy version to `.tool-versions`
e.g.: `rtx local --fuzzy nodejs@18` will save `nodejs 18` to .tool-versions this is the default behavior unless RTX_ASDF_COMPAT=1
--remove <PLUGIN>
Remove the plugin(s) from .tool-versions
Examples:
# set the current version of nodejs to 18.x for the current directory
# will use a precise version (e.g.: 18.0.0) in .tool-versions file
$ rtx local nodejs@18
# set nodejs to 18.x for the current project (recurses up to find .tool-versions)
$ rtx local -p nodejs@18
# set the current version of nodejs to 18.x for the current directory
# will use a fuzzy version (e.g.: 18) in .tool-versions file
$ rtx local --fuzzy nodejs@18
# removes nodejs from .tool-versions
$ rtx local --remove=nodejs
# show the current version of nodejs in .tool-versions
$ rtx local nodejs
18.0.0
List installed runtime versions
The "arrow (->)" indicates the runtime is installed, active, and will be used for running commands.
(Assuming `rtx activate` or `rtx env` is in use).
Usage: ls [OPTIONS]
Options:
-p, --plugin <PLUGIN>
Only show runtimes from [PLUGIN]
-c, --current
Only show runtimes currently specified in .tool-versions
Examples:
$ rtx list
-> nodejs 18.0.0 (set by ~/src/myapp/.tool-versions)
-> python 3.11.0 (set by ~/.tool-versions)
python 3.10.0
$ rtx list --current
-> nodejs 18.0.0 (set by ~/src/myapp/.tool-versions)
-> python 3.11.0 (set by ~/.tool-versions)
List runtime versions available for install
note that these versions are cached for commands like `rtx install nodejs@latest`
however _this_ command will always clear that cache and fetch the latest remote versions
Usage: ls-remote <PLUGIN> [PREFIX]
Arguments:
<PLUGIN>
Plugin to get versions for
[PREFIX]
The version prefix to use when querying the latest version same as the first argument after the "@"
Examples:
$ rtx ls-remote nodejs
18.0.0
20.0.0
$ rtx ls-remote nodejs@18
18.0.0
18.1.0
$ rtx ls-remote nodejs 18
18.0.0
18.1.0
Install a plugin
note that rtx automatically can install plugins when you install a runtime
e.g.: `rtx install nodejs@18` will autoinstall the nodejs plugin
This behavior can be modified in ~/.rtx/config.toml
Usage: install [OPTIONS] [NAME] [GIT_URL]
Arguments:
[NAME]
The name of the plugin to install
e.g.: nodejs, ruby
[GIT_URL]
The git url of the plugin
e.g.: https://github.com/asdf-vm/asdf-nodejs.git
Options:
-f, --force
Reinstall even if plugin exists
-a, --all
Install all missing plugins
This will only install plugins that have matching shorthands.
i.e.: they don't need the full git repo url
-v, --verbose...
Show installation output
Examples:
# install the nodejs plugin using the shorthand repo:
# https://github.com/asdf-vm/asdf-plugins
$ rtx install nodejs
# install the nodejs plugin using the git url
$ rtx install nodejs https://github.com/asdf-vm/asdf-nodejs.git
# install the nodejs plugin using the git url only
# (nodejs is inferred from the url)
$ rtx install https://github.com/asdf-vm/asdf-nodejs.git
List installed plugins
Can also show remotely available plugins to install.
Usage: ls [OPTIONS]
Options:
-a, --all
List all available remote plugins
same as `rtx plugins ls-remote`
-u, --urls
Show the git url for each plugin
e.g.: https://github.com/asdf-vm/asdf-nodejs.git
Examples:
$ rtx plugins ls
nodejs
ruby
$ rtx plugins ls --urls
nodejs https://github.com/asdf-vm/asdf-nodejs.git
ruby https://github.com/asdf-vm/asdf-ruby.git
List all available remote plugins
These are fetched from https://github.com/asdf-vm/asdf-plugins
Examples:
$ rtx plugins ls-remote
Usage: ls-remote [OPTIONS]
Options:
-u, --urls
Show the git url for each plugin
e.g.: https://github.com/asdf-vm/asdf-nodejs.git
Removes a plugin
Usage: uninstall <PLUGIN>
Arguments:
<PLUGIN>
Plugin to remove
Examples:
$ rtx uninstall nodejs
Updates a plugin to the latest version
note: this updates the plugin itself, not the runtime versions
Usage: update [OPTIONS] [PLUGIN]...
Arguments:
[PLUGIN]...
Plugin(s) to update
Options:
-a, --all
Update all plugins
Examples:
$ rtx plugins update --all # update all plugins
$ rtx plugins update nodejs # update only nodejs
[experimental] rebuilds the shim farm
this requires that the shims_dir is set
Usage: reshim
Examples:
$ rtx settings set experimental true
$ rtx settings set shims_dir ~/.rtx/shims
$ rtx reshim
$ ~/.rtx/shims/node -v
v20.0.0
Updates rtx itself
Usage: self-update
Show a current setting
This is the contents of a single entry in ~/.config/rtx/config.toml
Note that aliases are also stored in this file
but managed separately with `rtx aliases get`
Usage: get <KEY>
Arguments:
<KEY>
The setting to show
Examples:
$ rtx settings get legacy_version_file
true
Show current settings
This is the contents of ~/.config/rtx/config.toml
Note that aliases are also stored in this file
but managed separately with `rtx aliases`
Usage: ls
Examples:
$ rtx settings
legacy_version_file = false
Add/update a setting
This modifies the contents of ~/.config/rtx/config.toml
Usage: set <KEY> <VALUE>
Arguments:
<KEY>
The setting to set
<VALUE>
The value to set
Examples:
$ rtx settings set legacy_version_file true
Clears a setting
This modifies the contents of ~/.config/rtx/config.toml
Usage: unset <KEY>
Arguments:
<KEY>
The setting to remove
Examples:
$ rtx settings unset legacy_version_file
sets a runtime for the current shell session
Only works in a session where rtx is already activated.
Usage: shell [RUNTIME]...
Arguments:
[RUNTIME]...
Runtime version(s) to use
Examples:
$ rtx shell nodejs@18
$ node -v
v20.0.0
Removes runtime versions
Usage: uninstall <RUNTIME>...
Arguments:
<RUNTIME>...
Runtime(s) to remove
Examples:
$ rtx uninstall [email protected] # will uninstall specific version
$ rtx uninstall nodejs # will uninstall current nodejs version
Show rtx version
Usage: version
Display the installation path for a runtime
Must be installed.
Usage: where <RUNTIME>
Arguments:
<RUNTIME>
runtime(s) to look up if "@<PREFIX>" is specified, it will show the latest installed version that matches the prefix otherwise, it will show the current, active installed version
Examples:
# Show the latest installed version of nodejs
# If it is is not installed, errors
$ rtx where nodejs@18
/Users/jdx/.local/share/rtx/installs/nodejs/18.0.0
# Show the current, active install directory of nodejs
# Errors if nodejs is not referenced in any .tool-version file
$ rtx where nodejs
/Users/jdx/.local/share/rtx/installs/nodejs/18.0.0
shows the plugin that a bin points to
Usage: which <BIN_NAME>
Arguments:
<BIN_NAME>
Examples:
$ rtx which node
/home/username/.local/share/rtx/installs/nodejs/18.0.0/bin/node
rtx is mostly a clone of asdf, but there are notable areas where improvements have been made.
asdf made (what I consider) a poor design decision to use shims that go between a call to a runtime
and the runtime itself. e.g.: when you call node
it will call an asdf shim file ~/.asdf/shims/node
,
which then calls asdf exec
, which then calls the correct version of node.
These shims have terrible performance, adding ~120ms to every runtime call. rtx does not use shims and instead
updates PATH
so that it doesn't have any overhead when simply calling binaries. These shims are the main reason that I wrote this. Note that in the demo gif at the top of this README
that rtx
isn't actually used when calling node -v
for this reason. The performance is
identical to running node without using rtx.
I don't think it's possible for asdf to fix these issues. The author of asdf did a great writeup of performance problems. asdf is written in bash which certainly makes it challenging to be performant, however I think the real problem is the shim design. I don't think it's possible to fix that without a complete rewrite.
rtx does call an internal command rtx hook-env
every time the directory has changed, but because
it's written in Rust, this is very quick—taking ~10ms on my machine. 4ms if there are no changes, 14ms if it's
a full reload.
tl;dr: asdf adds overhead (~120ms) when calling a runtime, rtx adds a small amount of overhead (~10ms) when the prompt loads.
asdf only helps manage runtime executables. However, some tools are managed via environment variables
(notably Java which switches via JAVA_HOME
). This isn't supported very well in asdf and requires
a separate shell extension just to manage.
However asdf plugins have a bin/exec-env
script that is used for exporting environment variables
like JAVA_HOME
. rtx simply exports
the environment variables from the bin/exec-env
script in the plugin but places them in the shell
for all commands. In asdf it only exports those commands when the shim is called. This means if you
call java
it will set JAVA_HOME
, but not if you call some Java tool like mvn
.
This means we're just using the existing plugin script but because rtx doesn't use shims it can be used for more things. It would be trivial to make a plugin that exports arbitrary environment variables like dotenv or direnv.
Some commands are the same in asdf but others have been changed. Everything that's possible
in asdf should be possible in rtx but may use slightly different syntax. rtx has more forgiving commands,
such as using fuzzy-matching, e.g.: rtx install nodejs@18
. While in asdf you can run
asdf install nodejs latest:18
, you can't use latest:18
in a .tool-versions
file or many other places.
In rtx
you can use fuzzy-matching everywhere.
asdf requires several steps to install a new runtime if the plugin isn't installed, e.g.:
$ asdf plugin add nodejs
$ asdf install nodejs latest:18
$ asdf local nodejs latest:18
In rtx
this can all be done in a single step to set the local runtime version. If the plugin
and/or runtime needs to be installed it will prompt:
$ asdf local nodejs@18
rtx: Would you like to install [email protected]? [Y/n] Y
Trying to update node-build... ok
Downloading node-v18.13.0-darwin-arm64.tar.gz...
-> https://nodejs.org/dist/v18.13.0/node-v18.13.0-darwin-arm64.tar.gz
Installing node-v18.13.0-darwin-arm64...
Installed node-v18.13.0-darwin-arm64 to /Users/jdx/.local/share/rtx/installs/nodejs/18.13.0
$ node -v
v18.13.0
I've found asdf to be particularly rigid and difficult to learn. It also made strange decisions like
having asdf list all
but asdf latest --all
(why is one a flag and one a positional argument?).
rtx
makes heavy use of aliases so you don't need to remember if it's rtx plugin add nodejs
or
rtx plugin install nodejs
. If I can guess what you meant, then I'll try to get rtx to respond
in the right way.
That said, there are a lot of great things about asdf. It's the best multi-runtime manager out there and I've really been impressed with the plugin system. Most of the design decisions the authors made were very good. I really just have 2 complaints: the shims and the fact it's written in Bash.
Using rtx in CI/CD is a great way to synchronize tool versions for dev/build.
Use jdxcode/rtx-action
:
- uses: jdxcode/rtx-action@v1
- run: node -v # will be the node version from `.tool-versions`
While the PATH design of rtx works great in most cases, there are some situations where shims are preferable. One example is when calling rtx binaries from an IDE.
To support this, there is experimental support for using rtx in a "shim" mode. To use:
$ rtx settings set experimental true
$ rtx settings set shim_dir ~/.rtx/shims
$ rtx i [email protected]
$ rtx reshim
$ ~/.rtx/shims/node -v
v18.0.0
direnv and rtx both manage environment variables based on directory. Because they both analyze the current environment variables before and after their respective "hook" commands are run, they can conflict with each other. As a result, there were a number of issues with direnv. However, we think we've mitigated these. If you find that rtx and direnv are not working well together, please comment on that ticket ideally with a good description of your directory layout so we can reproduce the problem.
If there are remaining issues, they're likely to do with the ordering of PATH. This means it would
really only be a problem if you were trying to manage the same runtime with direnv and rtx. For example,
you may use layout python
in an .envrc
but also be maintaining a .tool-versions
file with python
in it as well.
A more typical usage of direnv would be to set some arbitrary environment variables, or add unrelated binaries to PATH. In these cases, rtx will not interfere with direnv.
As mentioned in the Quick Start, it is important to make sure that rtx activate
is called after direnv hook
in the shell rc file. rtx overrides some of the internal direnv state (DIRENV_DIFF
) so calling
direnv first gives rtx the opportunity to make those changes to direnv's state.
If you do encounter issues with rtx activate
, or just want to use direnv in an alternate way,
this is a simpler setup that's less likely to cause issues.
To do this, first use rtx
to build a use_rtx
function that you can use in .envrc
files:
$ rtx direnv activate > ~/.config/direnv/lib/use_rtx.sh
Now in your .envrc
file add the following:
use rtx
direnv will now call rtx to export its environment variables. You'll need to make sure to add use_rtx
to all projects that use rtx (or use direnv's source_up
to load it from a subdirectory). You can also add use rtx
to ~/.config/direnv/direnvrc
.
Note that in this method direnv typically won't know to refresh .tool-versions
files
unless they're at the same level as a .envrc
file. You'll likely always want to have
a .envrc
file next to your .tool-versions
for this reason. To make this a little
easier to manage, I encourage not actually using .tool-versions
at all, and instead
setting environment variables entirely in .envrc
:
export RTX_NODEJS_VERSION=18.0.0
export RTX_PYTHON_VERSION=3.11
Of course if you use rtx activate
, then these steps won't have been necessary and you can use rtx
as if direnv was not used.
rtx makes use of caching in many places in order to be efficient. The details about how long to keep cache for should eventually all be configurable. There may be gaps in the current behavior where things are hardcoded but I'm happy to add more settings to cover whatever config is needed.
Below I explain the behavior it uses around caching. If you're seeing behavior where things don't appear to be updating, this is a good place to start.
Each plugin has a cache that's stored in ~/$RTX_CACHE_DIR/plugins/<PLUGIN>
. It stores
the list of versions available for that plugin (rtx ls-remote <PLUGIN>
), the legacy filenames (see below),
the list of aliases, and the bin directories within each runtime installation.
Remote versions are updated daily by default or anytime that rtx ls-remote
is called explicitly. The file is
zlib messagepack, if you want to view it you can run the following (requires msgpack-cli).
cat ~/$RTX_CACHE_DIR/nodejs/remote_versions.msgpack.zlib | perl -e 'use Compress::Raw::Zlib;my $d=new Compress::Raw::Zlib::Inflate();my $o;undef $/;$d->inflate(<>,$o);print $o;' | msgpack-cli decode
If enabled, rtx will read the legacy filenames such as .node-version
for
asdf-nodejs. This leverages cache in 2 places where the
plugin is called:
list-legacy-filenames
In every plugin I've seen this simply returns a static list of filenamed like ".nvmrc .node-version". It's cached alongside the standard "runtime" cache which is refreshed daily by default.parse-legacy-file
This plugin binary is called to parse a legacy file to get the version out of it. It's relatively expensive so every file that gets parsed as a legacy file is cached into~/.local/share/rtx/legacy_cache
. It will remain cached until the file is modified. This is a simple text file that has the path to the legacy file stored as a hash for the filename.
Run tests with just
:
$ just test
Lint the codebase with:
$ just lint-fix