lpm use

Select the Node.js or Bun version that your project needs. LPM CLI stores managed runtimes once and shares them across projects on the same machine.

lpm use [OPTIONS] [ARGS]...

lpm use [install|i] <runtime>@<spec>
lpm use pin <runtime>@<spec>
lpm use [list|ls] [runtime]
lpm use [remove|rm|uninstall] <runtime>@<spec>

Quickstart

lpm use node@22
lpm run dev

The first command installs the highest matching Node release and writes its exact version to lpm.json. Project scripts then receive that runtime on PATH.

Supported runtimes are node and bun. A bare version such as lpm use 22 selects Node. With no arguments, the command lists installed Node versions.

These modes are non-interactive. Use --json for automation.

Project configuration

{
  "runtime": {
    "node": "22.12.0",
    "bun": "1.3.14"
  }
}

lpm run, lpm dev, and other runtime-aware commands read these pins. They install missing versions automatically unless automatic installation is off.

For Node, runtime.node takes precedence over .nvmrc, then .node-version. Bun reads runtime.bun only.

package.json > engines.node checks compatibility. It does not select or install a runtime. engines.bun produces a compatibility warning.

A Bun pin adds Bun to PATH. It does not change the script runner to bun run.

To change a project pin:

lpm use node@22.12.0
lpm use bun@1.3.14

LPM CLI writes the pin to lpm.json in the nearest directory at or above the current one that has a package.json or an lpm.json, stopping before your home directory. It prints that directory when it is not the current one. Without such a directory, it uses the current directory. It preserves unrelated configuration fields and leaves .nvmrc and .node-version unchanged.

To disable automatic downloads for one run:

LPM_NO_AUTO_INSTALL=1 lpm run dev

If a selected runtime is missing, LPM CLI warns and leaves the inherited PATH available. This setting does not disable an explicit installation through this command.

See Managed runtimes for workspace inheritance, PATH order, and supported hosts.

Version selectors

Quote selectors that contain spaces or shell operators:

lpm use node@22
lpm use node@lts
lpm use node@lts/iron
lpm use 'node@>=22 <23'
lpm use 'node@20 || 22'
lpm use bun@latest
lpm use 'bun@~1.3.0'

Bun also accepts the bun-v prefix, such as bun@bun-v1.3.14. Bun has no LTS channel.

Invalid selectors and contradictory ranges fail before the project pin changes. A valid selector with no matching release also fails during installation.

An exact installed version needs no release lookup. Other install selectors use release metadata, which LPM CLI caches for one hour.

Automatic runs prefer matching installed versions. They can reuse installed Node LTS versions from older cached metadata without a download.

Pin without a download

lpm use pin node@22
lpm use pin bun@1.3
lpm use pin node@22.12.0 --json

If an installed version matches, the command pins the highest match. Otherwise, it stores the valid selector and warns that the runtime is missing.

Node channel selectors such as lts remain selectors during pin-only use. Bun latest selects the highest installed Bun version if one exists.

Pin-only use can prepare lpm.json in an offline environment. A later runtime-aware command can download the missing runtime.

List and remove versions

lpm use list node
lpm use list bun --json
lpm use remove node@20
lpm use remove 'bun@>=1.2 <1.3'

Listing omits incomplete directories and invalid runtime executables. Removal uses the local installed set and waits for an active installation of the same version.

Channel selectors such as latest and lts/iron are not removal selectors. Use an exact version, prefix, wildcard, or range.

Removal does not change lpm.json. If the project pin matches a removed version, the command warns that a later run can install it again.

A remaining Node channel pin also produces a warning. Channel selection depends on release metadata.

To replace an old pin before removal:

lpm use node@22
lpm use remove node@20

Downloads and recovery

LPM CLI downloads Node from its distribution service and Bun from its GitHub releases. Package registry settings do not change these runtime sources.

Downloads require matching SHA-256 checksums. LPM CLI checks the expected executable before it publishes an installation. A failed download does not create a complete installed version.

Runtimes live under ~/.lpm/runtimes/node/ and ~/.lpm/runtimes/bun/. LPM_HOME changes the storage root.

If an installation is incomplete or its executable is invalid, repeat the exact installation:

lpm use node@22.12.0
lpm use bun@1.3.14

If installation succeeds but the project configuration cannot be written, the runtime remains installed. Correct the configuration or its permissions, then pin it:

lpm use pin node@22.12.0

JSON output and flags

lpm use node@22.12.0 --json
lpm use --list bun --json
lpm use remove bun@1.3.14 --json

Install output reports the runtime, exact version, installation status, and pin status. Pin output reports whether that version is installed. List output contains runtime and versions.

If installation succeeds but pinning fails, JSON reports status: "installed_not_pinned" and the command exits with a nonzero status.

--list, --pin, and --remove conflict with each other. See global flags for shared options.

See also

• Managed runtimes — runtime detection, automatic installation, and script PATH.
• lpm run — run project scripts with the selected runtimes.
• lpm dev — start development services.
• lpm env — manage project environment variables and secrets.