Move an asdf project to OMG

Keep your .tool-versions, select runtimes with OMG, eliminate shell shim latency, and migrate without deleting your existing asdf installation.

OMG maintainers · Updated · Source-reviewed guide

Check existing .tool-versions without deleting asdf

Migrating an existing project from asdf to OMG does not require deleting your ~/.asdf directory or converting your configuration files. OMG natively reads .tool-versions files in your repositories.

OMG installs runtimes into its own versions directory (~/.local/share/omg/versions/); it does not import or execute from ~/.asdf/installs/. Record the active versions your project uses before updating your shell.

Review the current .tool-versions file and active versions

cat .tool-versions
asdf current

Install corresponding runtimes with OMG

Use omg use to install the runtime versions declared in your .tool-versions file. OMG verifies archive checksums and extracts the toolchains into its local cache.

Install matching tool versions via OMG

omg use node 20
omg use python 3.12
omg list

Update shell configuration to avoid shim conflicts

asdf uses shims (~/.asdf/shims) placed at the front of your PATH. To ensure OMG resolves binaries without wrapper latency, comment out the asdf initialization line in your shell profile (~/.bashrc, ~/.zshrc, or config.fish) rather than deleting it.

Add the OMG shell integration line to your profile, then restart your shell session to confirm that binaries resolve directly through OMG.

Verify that binaries resolve directly through OMG without shims

which -a node
which -a python
omg which node

Run project tests and verify lockfiles

Execute your standard project build and test commands to verify identical behavior. Keep .tool-versions committed in the repository so colleagues using either tool can resolve the correct version.

You can also run omg env capture to record your environment into omg.lock and verify drift across machines with omg env check.

Execute project verification and capture environment state

node --version
npm test
omg env capture
omg env check

Sources and verification

Commands and behavior are based on the references below. Source review is not a claim that every workflow has been executed on every supported platform.

Read as Markdown