# 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.

Canonical: https://getomg.xyz/guides/migrate-from-asdf/
Updated: 2026-09-21
Author: OMG maintainers

## Check existing .tool-versions without deleting asdf

> There are no automated migration subcommands. omg migrate only supports export and import of portable environment manifests. Migration from asdf is manual, non-destructive, and reuses your existing .tool-versions files.

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

```sh
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

```sh
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

```sh
which -a node
which -a python
omg which node
```

> Because OMG modifies PATH directly upon directory change, which node points directly to the real binary in the OMG versions tree rather than an asdf shim wrapper script.

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

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

## Sources and verification

Source-reviewed guidance; not a claim of execution on every supported platform.

- [OMG runtime handbook](https://getomg.xyz/docs/runtimes/)

- [OMG vs asdf comparison](https://getomg.xyz/compare/omg-vs-asdf/)

- [asdf documentation](https://asdf-vm.com/)

## Related pages

- https://getomg.xyz/compare/omg-vs-asdf/

- https://getomg.xyz/guides/migrate-from-nvm/

- https://getomg.xyz/guides/reproducible-dev-environments/

- https://getomg.xyz/runtimes/node/