Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update troubleshooting.md #814

Merged
merged 1 commit into from
May 18, 2022
Merged

Update troubleshooting.md #814

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 30 additions & 14 deletions docs/troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,24 +2,40 @@

If you have trouble installing `better-sqlite3`, follow this checklist:

1. Make sure you're using nodejs v10.20.1 or later
## Install a recent Node.js

2. Make sure there are no spaces in the path of the directory you are installing in
1. Make sure you're using Node.js v14.19.2 or later.
2. If you're on Windows, while installing, be sure to select "Automatically install the necessary tools" on the "Tools for Native Modules" page, and follow the remaining steps, including opening an admin PowerShell and installing visual studio and python. Everything _should_ just work.

3. Make sure you have [`node-gyp`](https://github.com/nodejs/node-gyp#installation) globally installed, including all of [its dependencies](https://github.com/nodejs/node-gyp#on-unix). On Windows you may need to [configure some things manually](https://github.com/nodejs/node-gyp#on-windows). Use `npm ls node-gyp` to make sure none of your local packages installed an outdated version of `node-gyp` that is used over the global one.
## Install the `node-gyp` toolchain

4. If you're using [Electron](https://github.com/electron/electron), try running [`electron-rebuild`](https://www.npmjs.com/package/electron-rebuild)
1. Make sure you have [`node-gyp`](https://github.com/nodejs/node-gyp#installation) globally installed
1. Make sure all [`node-gyp` dependencies are installed](https://github.com/nodejs/node-gyp#on-unix). On Windows you may need to [configure some things manually](https://github.com/nodejs/node-gyp#on-windows). Use `npm ls node-gyp` to make sure none of your local packages installed an outdated version of `node-gyp` that is used over the global one.

5. If you're using Windows, follow these steps. Do them **in this order**, and **don't skip steps**.
## No special characters in your project path

1. Install the **latest** of node 10, 12, or 14.
2. Install **latest** Visual Studio Community and Desktop Development with C++ extension.
3. Install **latest** Python.
4. Run following commands:
```
npm config set msvs_version 2019
npm config set msbuild_path "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\MSBuild\Current\Bin\MSBuild.exe"
```
5. Run `npm install`
1. Make sure there are no spaces in your project path: `node-gyp` may not escape spaces or special characters (like `%` or `$`) properly.

## Electron

1. If you're using [Electron](https://github.com/electron/electron), try running [`electron-rebuild`](https://www.npmjs.com/package/electron-rebuild)

## Windows

If you still have issues on Windows and are on an older version of Node, try these steps:

1. Install the **latest** of node 12, 14, or 16.
1. Install **latest** Visual Studio Community and Desktop Development with C++ extension.
1. Install **latest** Python.
1. Run following commands:
```
npm config set msvs_version 2019
npm config set msbuild_path "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\MSBuild\Current\Bin\MSBuild.exe"
```
1. Delete your `node_modules` subdirectory
1. Delete your `$HOME/.node-gyp` directory
1. Run `npm install`

## If all else fails

If none of these solved your problem, try browsing [previous issues](https://github.com/JoshuaWise/better-sqlite3/issues?q=is%3Aissue) or open a [new issue](https://github.com/JoshuaWise/better-sqlite3/issues/new).