rtx

Polyglot runtime manager

Quickstart (macOS)

Install rtx (other methods here):

$ brew install jdxcode/tap/rtx
$ rtx --version
rtx 0.1.1-alpha.16

Hook rtx into to your shell (choose one):

$ echo 'eval "$(rtx activate -s bash)"' >> ~/.bashrc
$ echo 'eval "$(rtx activate -s zsh)"' >> ~/.zshrc
$ echo 'rtx activate -s fish | source' >> ~/.config/fish/config.fish

Note
Open a new shell session for the changes to take effect.

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

rtx is a tool for managing programming language versions. For example, use this to install a particular version of node.js and ruby for a project. Using rtx activate, you can also have your shell automatically switch to the correct node and ruby versions when you cd into the project's directory.

rtx is inspired by asdf and uses asdf's plugin ecosystem under the hood. However it is much faster than asdf with a more friendly user experience. For more on how rtx compares to asdf, see below.

How it works

rtx installs as a shell extension (e.g. rtx activate -s zsh) that sets the PATH and other environment variables to point to the correct runtime versions. When you cd into a directory containing a .tool-versions file, rtx will automatically activate the correct versions.

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 a hefty 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.

Common example commands

rtx install [email protected]          Install a specific version number
rtx install [email protected]            Install a fuzzy version number
rtx local nodejs@20                Use node-20.x in current project
rtx global nodejs@20               Use node-20.x as default

rtx install nodejs                 Install the latest available version
rtx local nodejs                   Use latest node in current directory
rtx global system                  Use system node as default

rtx exec nodejs@20 -- node app.js  Run `node app.js` with the PATH pointing to node-20.x

Installation

Warning
Regardless of the installation method, when uninstalling rtx, remove $RTX_DATA_DIR folder (usually ~/.local/share/rtx) to fully clean up.

Homebrew

$ brew install jdxcode/tap/rtx

Cargo

$ cargo install rtx-cli

npm

$ npm install -g rtx-cli

GitHub Releases

Download the latest release from GitHub.

$ curl https://github.com/rtx-vm/rtx/releases/rtx-latest-macos-arm64.tar.xz | tar -xJ

Ubuntu

TODO

Arch Linux

TODO

Other Shells

Bash

$ echo 'eval "$(rtx activate -s bash)"' >> ~/.bashrc

Fish

$ rtx activate -s fish | source

Configuration

.tool-versions

The .tool-versions file is used to specify the runtime versions for a project. An example of this is:

nodejs 20.0.0  # comments are allowed
ruby 3.0.0

Create .tool-versions files manually, or use rtx local to create them automatically.

Global config: ~/.config/rtx/config.toml

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, .node-version in the case of nodejs's nvm
legacy_version_file = false         # not enabled by default

# 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
plugin_autoupdate_last_check_duration = 10080 # (one week) set to 0 to disable updates

# configure how frequently (in minutes) to fetch updated shortname repository changes
# note this is not plugins themselves, it's the shortname mappings
# e.g.: nodejs -> https://github.com/asdf-vm/asdf-nodejs.git
plugin_repository_last_check_duration = 10080 # (one week) set to 0 to disable updates

# disables the short name repository (described above)
disable_plugin_short_name_repository = false

rtx can also be configured via environment variables. The following options are available:

RTX_MISSING_RUNTIME_BEHAVIOR

This is the same as the missing_runtime_behavior config option in ~/.config/rtx/config.toml.

RTX_DATA_DIR

This is the directory where rtx stores its data. The default is ~/.local/share/rtx.

$ RTX_MISSING_RUNTIME_BEHAVIOR=ignore rtx install nodejs@20
$ RTX_NODEJS_VERSION=20 rtx exec -- node --version

RTX_CONFIG_FILE

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)

RTX_DEFAULT_TOOL_VERSIONS_FILENAME

Set to something other than ".tool-versions" to have rtx look for configuration with alternate names.

RTX_${PLUGIN}_VERSION

Set the version for a runtime. For example, RTX_NODEJS_VERSION=20 will use [email protected] regardless of what is set in .tool-versions.

Plugins

rtx uses asdf's plugin ecosystem under the hood. See https://github.com/asdf-vm/asdf-plugins for a list.

FAQs

I don't want to put a .tool-versions file into my project since git shows it as an untracked file.

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 with git add --force .tool-versions.

How do I create my own plugin?

Windows support?

This is unlikely to ever happen since this leverages the vast ecosystem of asdf plugins which are built on Bash scripts. At some point it may be worth exploring an alternate plugin format that would be Windows compatible.

Comparison to asdf

rtx improves on asdf in 2 places: UX and performance.

Performance

asdf made a poor design decision to use shims that go between a call to a runtime and then runtime itself. e.g.: when you call node it will call an asdf shim file which then calls the correct version of node.

These shims are the main reason that I wrote this.

These shims have terrible performance, adding ~200ms to every call. rtx does not use shims and instead updates $PATH so that it doesn't any any overhead when simply calling binaries.

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 ~15ms on my machine. This can probably be tuned to be even faster.

tl;dr: asdf adds overhead (~200ms) when calling a runtime, rtx adds overhead (~15ms) when changing directories.

UX

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 slighly 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

I've found asdf to be particularly rigid and difficult to learn. 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. asdf also just has too many commands. It's hard to remember what the difference is between asdf list and asdf current is. rtx has a single command rtx list which can be passed a flag rtx list --current to show the current versions.

Commands

rtx activate

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]

Options:
  -s, --shell <SHELL>
          Shell type to generate script for
          
          [possible values: bash, fish, zsh]

  -h, --help
          Print help (see a summary with '-h')


Examples:
    $ eval "$(rtx activate -s bash)"
    $ eval "$(rtx activate -s zsh)"
    $ rtx activate -s fish | source

rtx deactivate

disable rtx for current shell session

This can be used to temporarily disable rtx from automatically modifying $PATH.

Usage: deactivate [OPTIONS]

Options:
  -s, --shell <SHELL>
          shell type to generate the script for
          
          e.g.: bash, zsh, fish
          
          [possible values: bash, fish, zsh]

  -h, --help
          Print help (see a summary with '-h')


Examples:
    $ eval "$(rtx deactivate -s bash)"
    $ eval "$(rtx deactivate -s zsh)"
    $ rtx deactivate -s fish | source

rtx doctor

Check rtx installation for possible problems.

Usage: doctor

Options:
  -h, --help
          Print help (see a summary with '-h')


Examples:
  $ rtx doctor

rtx env

exports environment variables to use rtx in current directory

Use this to modify a single shell session to have rtx enabled.
`rtx activate` will do this automatically.
Use this if you don't want to permanently install rtx.

Usage: env [OPTIONS]

Options:
  -s, --shell <SHELL>
          Shell type to generate environment variables for
          
          [possible values: bash, fish, zsh]

  -r, --runtime <RUNTIME>
          runtime version to use

  -h, --help
          Print help (see a summary with '-h')


Examples:
  $ eval "$(rtx env -s bash)"
  $ eval "$(rtx env -s zsh)"
  $ rtx env -s fish | source

rtx exec

execute a command with runtime(s) set

use this to avoid modifying the shell session or to run ad-hoc commands with
alternate runtimes set.

This will default the runtimes to the same .tool-version config in other commands.

Usage: exec [OPTIONS] [COMMAND]...

Arguments:
  [COMMAND]...
          the command string to execute (same as --command)

Options:
  -r, --runtime <RUNTIME>
          runtime(s) to start
          
          e.g.: nodejs@20 [email protected]

  -c, --command <C>
          the command string to execute

  -h, --help
          Print help (see a summary with '-h')


Examples:
  rtx exec nodejs@20 -- node ./app.js
  rtx exec --runtime nodejs@20 -- node ./app.js

Specify command as a string:
  rtx exec nodejs@20 [email protected] --command "node -v && python -V"

rtx global

sets global .tool-versions to include a specific runtime

this 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]...
          runtimes
          
          e.g.: nodejs@20

Options:
      --fuzzy
          save fuzzy match to .tool-versions e.g.: `rtx global --fuzzy nodejs@20` will save `nodejs 20` to .tool-versions by default it would save the exact version, e.g.: `nodejs 20.0.0`

  -h, --help
          Print help (see a summary with '-h')


Examples:
  # set the current version of nodejs to 20.x
  # will use a precise version (e.g.: 20.0.0) in .tool-versions file
  $ rtx global nodejs@20     

  # set the current version of nodejs to 20.x
  # will use a fuzzy version (e.g.: 20) in .tool-versions file
  $ rtx global --fuzzy nodejs@20

rtx install

install a runtime

Usage: install [OPTIONS] [RUNTIME]...

Arguments:
  [RUNTIME]...
          runtime(s) to install
          
          e.g.: nodejs@20

Options:
  -p, --plugin <PLUGIN>
          only install runtime(s) for <PLUGIN>

  -h, --help
          Print help (see a summary with '-h')


Examples:
  $ rtx install [email protected]  # install specific nodejs version
  $ rtx install nodejs@18      # install fuzzy nodejs version
  $ rtx install nodejs         # install latest nodejs version—or what is specified in .tool-versions
  $ rtx install                # installs all runtimes specified in .tool-versions

rtx latest

get the latest runtime version of a plugin's runtimes

Usage: latest <RUNTIME>

Arguments:
  <RUNTIME>
          Runtime to get the latest version of

Options:
  -h, --help
          Print help (see a summary with '-h')


Examples:
  $ rtx latest nodejs@18  # get the latest version of nodejs 18
  18.0.0
  
  $ rtx latest nodejs     # get the latest version of nodejs
  20.0.0

rtx list

list installed runtime versions

Usage: list [OPTIONS]

Options:
  -p, --plugin <PLUGIN>
          Only show runtimes from [PLUGIN]

  -c, --current
          Only show runtimes currently specified in .tool-versions

  -h, --help
          Print help (see a summary with '-h')


Examples:
  $ rtx list
  -> nodejs     20.0.0 (set by ~/src/myapp/.rtxrc)
  -> python     3.11.0 (set by ~/.rtxrc)
     python     3.10.0
     
  $ rtx list --current
  -> nodejs     20.0.0 (set by ~/src/myapp/.rtxrc)
  -> python     3.11.0 (set by ~/.rtxrc)

rtx list-remote

list runtime versions available for install

Usage: list-remote <PLUGIN>

Arguments:
  <PLUGIN>
          Plugin

Options:
  -h, --help
          Print help (see a summary with '-h')


Examples:
  $ rtx list-remote nodejs
  18.0.0
  20.0.0

rtx local

sets .tool-versions to include a specific runtime

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
          
          e.g.: nodejs@20

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")

      --fuzzy
          save fuzzy match to .tool-versions e.g.: `rtx local --fuzzy nodejs@20` will save `nodejs 20` to .tool-versions by default it would save the exact version, e.g.: `nodejs 20.0.0`

  -h, --help
          Print help (see a summary with '-h')


Examples:
  # set the current version of nodejs to 20.x for the current directory
  # will use a precise version (e.g.: 20.0.0) in .tool-versions file
  $ rtx local nodejs@20     

  # set nodejs to 20.x for the current project (recurses up to find .tool-versions)
  $ rtx local -p nodejs@20  
  
  # set the current version of nodejs to 20.x for the current directory
  # will use a fuzzy version (e.g.: 20) in .tool-versions file
  $ rtx local --fuzzy nodejs@20

rtx plugins install

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
          Reinstalls even if plugin exists

  -h, --help
          Print help (see a summary with '-h')


EXAMPLES:
    $ rtx install nodejs  # install the nodejs plugin using the shorthand repo:
                          # https://github.com/asdf-vm/asdf-plugins

    $ rtx install nodejs https://github.com/asdf-vm/asdf-nodejs.git
                          # install the nodejs plugin using the git url

    $ rtx install https://github.com/asdf-vm/asdf-nodejs.git
                          # install the nodejs plugin using the git url only
                          # (nodejs is inferred from the url)

rtx plugins list

List installed plugins
Can also show remotely available plugins to install.

Examples:

  $ rtx plugins list
  nodejs
  ruby
  
  $ rtx plugins list --urls
  nodejs                        https://github.com/asdf-vm/asdf-nodejs.git
  ruby                          https://github.com/asdf-vm/asdf-ruby.git


Usage: list [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

  -h, --help
          Print help (see a summary with '-h')

rtx plugins list-remote

List all available remote plugins

These are fetched from https://github.com/asdf-vm/asdf-plugins

Examples:
  $ rtx plugins ls-remote


Usage: list-remote [OPTIONS]

Options:
  -u, --urls
          show the git url for each plugin
          
          e.g.: https://github.com/asdf-vm/asdf-nodejs.git

  -h, --help
          Print help (see a summary with '-h')

rtx plugins uninstall

removes a plugin

Usage: uninstall <PLUGIN>

Arguments:
  <PLUGIN>
          plugin to remove

Options:
  -h, --help
          Print help (see a summary with '-h')


Examples:
  $ rtx uninstall nodejs

rtx plugins update

updates a plugin to the latest version

note: this updates the plugin itself, not the runtime versions

Usage: update [PLUGIN]...

Arguments:
  [PLUGIN]...
          plugin(s) to update

Options:
  -h, --help
          Print help (see a summary with '-h')


Examples:
  rtx plugins update         # update all plugins
  rtx plugins update nodejs  # update only nodejs

rtx uninstall

removes a runtime version

Usage: uninstall <RUNTIME>...

Arguments:
  <RUNTIME>...
          runtime(s) to remove

Options:
  -h, --help
          Print help (see a summary with '-h')


Examples:
  $ rtx uninstall nodejs

rtx version

Show rtx version

Usage: version

Options:
  -h, --help
          Print help

Development

Run tests with just:

$ just test

E2E tests are run with:

$ just e2e