Skip to main content

GitHub package.json version npm (scoped) NPM Downloads NPM Downloads

How to install xpm

Prerequisites​

  • a recent Node.js ("engines.node": ">=18.0.0")
  • a recent npm (installed by Node.js)

For first-time Node.js users, it is highly recommended to read the instructions on the xPack Prerequisites page.

Quick instructions​

For those who have already performed the install steps on the xPack Prerequisites page and are familiar with the process, here are the commands you need. Simply copy and paste them into your terminal (hover the mouse over the command, and 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 and install it as usual, with administrative rights. Avoid selecting the Tools for Native Modules during installation.

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

Install​

caution

Please be sure that the xpm you are trying to install is the xPack Project Manager, since there are other projects that unfortunately use the same name (for example verseles/xpm, the uniX Package Manager).

With the environment properly set, the command to install xpm is:

npm install --location=global xpm@latest

This command installs the latest available version.

To install a specific version, mention it explicitly:

npm install --location=global xpm@0.20.5

On Windows, global Node.js packages are installed in the user home folder, in %APPDATA%\npm (like 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 program should start normally:

C:>xpm --version
0.20.5

Troubleshooting

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 is:

npm uninstall --location=global xpm

Do not install npm with administrative rights!​

Installing npm with administrative rights is strongly discouraged, as it leads to installing all other CLI programs (including xpm) with administrative rights as well. Instead, use a node version manager.

For completeness, the official page explaining how to install npm in a custom folder is Resolving EACCES permissions errors when installing packages globally.

npx​

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

$ npx xpm --version
0.20.5

However, for regular usage, this method is not efficient, since npx will need to prepare the Node.js module for each run, and this takes some time.

npm folders​

For more details on the folders used by npm, see 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.20.5 '/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/>
%