Skip to main content

How to install xpm

GitHub package.json version NPM Version NPM Downloads NPM Downloads license

Prerequisites​

Installing xpm requires:

  • A recent version of Node.js (specified as "engines.node": ">=20.0.0")
  • A recent version of npm which is installed alongside Node.js

For those new to Node.js, it is highly recommended to read the instructions on the xPack Prerequisites page.

Quick instructions​

For those who have already completed the installation steps on the xPack Prerequisites page and are familiar with the process, here are the necessary commands. Simply copy and paste them into your terminal. When you hover the mouse over the command, a copy button will appear on the right side; click it to copy the command.

Download the Windows Prebuilt Installer (a node-v*-x64.msi file) from the Download Node.js page. Select the latest LTS version and install it as usual, ensuring you have administrative rights.

tip

Unless specifically required, refrain from selecting the Tools for Native Modules during installation, as this will result in the installation of some very large Microsoft tools.

Although not mandatory, it is recommended to update npm to the latest version:

npm install -location=global npm@latest

Update the user Path and make it persistent:

set Path=%APPDATA%\npm;%Path%
setx Path "%APPDATA%\npm;%Path%"

Configure PowerShell to allow the execution of node.js applications:

Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope CurrentUser

Installation​

caution

Please ensure that the xpm you are attempting to install is the xPack Project Manager, as there are other projects that unfortunately share the same name (for example, verseles/xpm, the uniX Package Manager).

The package is available as xpm from the public npmjs repository; it may be added as a development dependency to any npm project or it may be installed into the user's global environment.

Project installation​

The command to install the latest available version of xpm as a development dependency in an npm project is:

npm install xpm@latest --save-dev

For a specific version, use the explicit version numbers:

npm install xpm@0.21.4 --save-dev

Global installation​

Since the package includes command-line tools, it may also be installed globally and utilised in any project.

npm install --location=global xpm@latest

For a specific version, use the explicit version numbers:

npm install --location=global xpm@0.21.4

On Windows, global Node.js packages are installed in the user home folder, within %APPDATA%\npm (such as C:\Users\ilg\AppData\Roaming\npm), and managing packages does not require administrative rights.

The result of installing xpm is a set of files in the %APPDATA%\npm folder:

C:\>dir "%APPDATA%"\npm\xpm*
 Volume in drive C has no label.
 Volume Serial Number is B02D-925C

 Directory of C:\Users\ilg\AppData\Roaming\npm

29/07/2024  07:24               397 xpm
29/07/2024  07:24               329 xpm.cmd
29/07/2024  07:24               821 xpm.ps1
               3 File(s)          1,547 bytes
               0 Dir(s)  39,088,439,296 bytes free

If you followed the instructions in the prerequisites section, you should already have this path configured and the programme should start normally:

C:>xpm --version
0.21.4

Troubleshooting

danger

By design, xpm utilises symbolic links to folders (junction points on NTFS) to facilitate the sharing of common packages across projects. Any attempt to install packages on a drive that does not support symbolic links will result in an error:

error: volume X: does not support links, it might not be NTFS, or it might be a remote resource

Utilise a recent version of Windows and format the drive as NTFS.

error: Cannot read property 'path' of null

A common source of errors is an aggressive antivirus. See the FAQ page for details.

... running scripts is disabled

This error is caused by a Power Shell setting. See the FAQ page for details.

Uninstall​

The command to remove xpm from a project is:

npm uninstall xpm

The command to remove xpm from the global user environment is:

npm uninstall --location=global xpm

npx​

If, for any reason, you decide not to install xpm, you can still benefit from it by utilising the npx command, as a trampoline to start xpm:

$ npx --package xpm -- xpm --version
0.21.4

However, for regular use, this method may be less convenient, as invoking npx requires a more verbose command.

npm folders​

For more details on the folders used by npm, refer to npm-folders.

xpm folders​

To avoid security issues and the need for elevated user privileges, xpm operates entirely within the user home folder, avoiding the use of system folders.

The folders in use are:

  • A cache folder, where all downloaded files are stored
  • A user global xPacks store folder, where the xpm packages are installed
Clean-ups

For a thorough clean-up, these folders can be removed at any time; xpm will recreate them on new installs.

  • %APPDATA%\Roaming\xPacks
  • %APPDATA%\Local\Caches\xPacks

For more details see xpm folders.

Proxy​

If you are behind a firewall, you need to configure a proxy.

xpm uses the same Node.js module as npm to fetch the packages metadata and content (pacote). Therefore, setting a proxy for npm will also work for xpm.

In addition, xpm uses node-fetch, https-proxy-agent, proxy-from-env to download the binary archives. These packages require setting the http_proxy & https_proxy variables in the environment. See proxy-from-env for details.

Quick info​

To get an initial overview of the program, request help by using the following command:

% xpm --help

The xPack project manager command line tool
Usage: xpm <command> [<subcommand>...] [<options> ...] [<args>...]

where <command> is one of:
init, install, link, list, run, uninstall

Common options:
--loglevel <level>     Set log level (silent|warn|info|verbose|debug|trace)
-s|--silent            Disable all messages (--loglevel silent)
-q|--quiet             Mostly quiet, warnings and errors (--loglevel warn)
--informative          Informative (--loglevel info)
-v|--verbose           Verbose (--loglevel verbose)
-d|--debug             Debug messages (--loglevel debug)
-dd|--trace            Trace messages (--loglevel trace, -d -d)
--no-update-notifier   Skip check for a more recent version
-C <folder>            Set current folder

xpm -h|--help            Quick help
xpm <command> -h|--help  Quick help on command
xpm --version            Show version
xpm -i|--interactive     Enter interactive mode

npm xpm@0.21.4 '/Users/ilg/.nvm/versions/node/undefined/lib/node_modules/xpm'
Home page: <https://xpack.github.io/xpm/>
Bug reports: <https://github.com/xpack/xpm-js/issues/>
%