Guide · Open source
How to use nexe: build a Node.js app into one executable
Updated · written with AI from the project's own documentation and checked against our catalogue data
Nexe is a command-line utility that compiles a Node.js application into a single executable file. This guide walks through installing it with npm, building your first executable, bundling extra files, and the build options the README covers. By the end you will know how to produce a binary that can run without Node or npm on the target machine, and when the setup is likely to be more work than it is worth.
nexenexe/nexe · ★ 13.6k · MIT Install options & downloads Quick start
- 1Install Node.js and npm. Make sure Node.js and npm are available on the machine where you will build the executable.
- 2Install nexe globally. Run npm i nexe -g to put the nexe command on your path.
- 3Build your entrypoint. Run nexe followed by your app file, such as my-app.js, to create an executable.
- 4Add resources if needed. Use -r with a glob pattern to include files such as HTML, then read them with fs.readFile in your app.
- 5Pick a target or build from source. Use -t to choose a runtime version, or --build with --python if you need a custom Node build.
- 6Run and distribute the binary. Run the output file and share it. According to the README, recipients do not need Node or npm installed.
Install nexe with npm
Nexe is installed through npm, so you need Node.js and npm on the machine where you build. The README gives a single global install command.
npm i nexe -gBuild your app into an executable
Pass your application's entrypoint to nexe. The README shows this form for a plain Node.js file. Run nexe --help to see the full list of CLI options.
You can also pipe a bundle into nexe on stdin, as in the README's rollup example, and set the output file with -o.
nexe my-app.jsBundle static files with resources
Extra files such as HTML or assets can be added to the binary with the -r flag and a glob pattern. According to the README, the included files can then be read in your application with fs.readFile or fs.readFileSync.
The README gives this example, which bundles HTML files from a public folder.
- Use -r or --resource with a quoted glob pattern.
- Read included files with fs.readFile or fs.readFileSync in your app.
nexe server.js -r "public/**/*.html"Choose a Node.js version or build Node yourself
By default nexe tries to download a pre-built executable, listed on the project's releases page. If you need a specific version, use the -t flag. To customize what is built, use --build, which the README says requires building Node from source.
Building needs an environment set up to build Node, and the python binary in your path should be a suitable version of Python 3. If it is not, the README says you can use the --python parameter.
- Use nexe -t with a version to target a specific runtime.
- Use nexe --build to build from source; add --clean to rebuild.
- If Python is not in your path, pass --python with the path to python3.
nexe --build --python=$(which python3)Use the Node.js API instead of the CLI
Nexe also exposes a compile function that you can call from a Node.js script. Options such as input, output, target, resources and build map to the CLI settings described in the README's NexeOptions section.
Options set in the API include input (defaults to stdin or the main file in package.json), output, and name. The README notes that the build option is required to use patches.
const { compile } = require('nexe')
compile({
input: './my-app.js',
build: true
}).then(() => {
console.log('success')
})Windows setup is the hard part
The README's Windows section is long. It asks you to run PowerShell as Administrator, install build tools with a Boxstarter bootstrapper, and set npm config values for Visual Studio and Python. The README says these steps were tested with specific Node.js versions, and advises against running npm install windows-build-tools unless you have a problem.
If you only need the default download path, the build tooling is not always required. Plan extra time for Windows if you plan to use --build.
What people use it for
- Handing a Node.js command-line tool to someone who does not have Node.js installed.
- Shipping a specific app version as one file so it can be rolled back easily.
- Bundling HTML or other static assets alongside a small Node.js server.
- Building a customized Node runtime with --build for a controlled environment.
Frequently asked questions
Is nexe free to use?
Nexe is released under the MIT licence, according to the project's README and metadata. You can use it in commercial and personal projects under the terms of that licence.
Do I need Node.js on the computer that runs the executable?
According to the README, the point of nexe is to distribute binaries without needing Node or npm on the target machine. You do need Node.js and npm on the machine where you build the file.
How do I install nexe?
Run npm i nexe -g from a terminal. This installs the nexe command globally, and you need Node.js and npm already installed.
Why does nexe --build fail?
The README says building Node from source needs Node's build setup and Python 3. Make sure your environment is set up for building Node, and pass --python with the path to python3 if python in your path is not a suitable version.
How does nexe compare to pkg, esbuild or Bun?
Comparable projects listed for this item include pkg, esbuild and Bun. This guide does not benchmark them; compare them against your own app and build requirements before choosing.
Can I include HTML or other files in the executable?
Yes. Use the -r flag with a glob pattern, such as public/**/*.html. The README says the files can be read in the app using fs.readFile or fs.readFileSync.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Nexe suits developers who want to give a Node.js program to people who do not have Node.js installed, or who want to pin one app version as a single file. It is a poor fit if you only need to run a script on your own machine, or if you expect a simple setup on Windows when you need to build from source.
Install options & downloads