Guide · Open source
How to use FingerprintJS: install, get a visitor ID and limits
Updated · written with AI from the project's own documentation and checked against our catalogue data
FingerprintJS is an open-source JavaScript library that reads browser attributes and combines them into a hashed visitor identifier that runs in the browser. It suits developers who want to recognize returning browsers in a web app without storing anything on the device. This guide shows you how to install it, get a visitor ID, and understand where it falls short.
FingerprintJSfingerprintjs/fingerprintjs · ★ 28.7k · MIT Install options & downloads Quick start
- 1Install the package. Run npm install @fingerprintjs/fingerprintjs in your project.
- 2Import FingerprintJS. Import the default export into your application code.
- 3Load the agent at startup. Call FingerprintJS.load() once so the agent is ready when you need it.
- 4Request the visitor ID. Call get() on the agent and read result.visitorId.
- 5Test in private mode. Open the page in a normal and a private window to confirm the identifier stays the same.
- 6Review the limits. Decide whether client-side accuracy and spoofing risk are acceptable for your use case.
What FingerprintJS does
FingerprintJS is a client-side, browser fingerprinting library. It queries browser attributes and computes a hashed visitor identifier from them.
Unlike cookies and local storage, the README says a fingerprint stays the same in incognito or private mode and even when browser data is purged. You can try this on the project's demo page by comparing the identifier in a normal window and a private window.
- Licence: MIT
- Language: TypeScript
- Runs in the browser, so fingerprints are generated and processed client-side
Install FingerprintJS with npm
Install the MIT-licensed package from npm. The README does not specify which Node.js version you need, so check your project's own requirements before you start.
Then import it in your app and initialize the agent once at startup.
npm install @fingerprintjs/fingerprintjsGet a visitor identifier in code
Call FingerprintJS.load() once when your application starts, then call get() when you need the identifier. The result object contains a visitorId property.
The README also documents a CDN option. It warns that ad blockers and Brave or Firefox may block that import, and recommends the npm package instead.
import FingerprintJS from '@fingerprintjs/fingerprintjs'
// Initialize the agent at application startup.
const fpPromise = FingerprintJS.load();
(async () => {
// Get the visitor identifier when you need it.
const fp = await fpPromise
const result = await fp.get()
console.log(result.visitorId)
})()Use the CDN script instead of npm
If you don't use a package manager, the README shows a script that imports FingerprintJS from a CDN URL and loads it the same way. A StackBlitz example is linked in the README for running it directly.
If the CDN import is blocked, switch to the npm package as the README suggests.
- Use the npm package when ad blockers or some browsers block the CDN import
- A React sample on StackBlitz is listed in the README
Understand the accuracy and security limits
The README says client-side accuracy is significantly lower than the commercial version. Because fingerprints are generated and processed in the browser, they can also be spoofed and reverse engineered.
So do not rely on FingerprintJS alone for fraud blocking or other security-critical decisions. The README also does not address privacy regulation, so check consent requirements for your own project.
- Do not use it alone for fraud blocking
- Plan your own consent handling for browser tracking
- Compare the commercial Fingerprint Identification product if you need higher accuracy
Where to find documentation and help
The README links to an API reference, a licensing page, a version policy, and a browser support guide. For bugs and questions, use the project's Issues and Discussions so others can benefit.
Comparable projects named in the analysis are ClientJS, Fingerprint2, and Evercookie.
- API reference: docs/api.md
- Browser support guide: docs/browser_support.md
- Support: GitHub Issues and Discussions
What people use it for
- Recognizing returning browsers in a web app without storing data on the device
- Testing basic visitor identification before deciding whether to pay for a more accurate service
- Adding a browser-side visitor identifier to an app through the npm package or a CDN script
Frequently asked questions
Is FingerprintJS free?
Yes, the library is published under the MIT license. The README also describes a commercial product, Fingerprint Identification, which is closed-source and separate from the open-source library.
How do I install FingerprintJS?
Run npm install @fingerprintjs/fingerprintjs. The README also shows a CDN script as an alternative, though it notes that ad blockers and some browsers may block it.
What are the requirements for FingerprintJS?
The README lists Node.js as a prerequisite but does not specify a version. It describes the library as running in the browser, and a browser support guide is linked in the README.
Does FingerprintJS work in incognito mode?
The README says the visitor identifier stays the same in incognito or private mode and even when browser data is purged. It suggests you test this yourself on the demo page.
How accurate is FingerprintJS compared to the paid version?
The README says client-side accuracy is significantly lower than the commercial version. The commercial product combines client-side signals with server-side processing, which the README says yields higher accuracy.
What are alternatives to FingerprintJS?
The analysis lists ClientJS, Fingerprint2, and Evercookie as comparable projects. The README does not compare them, so evaluate each one against your own requirements.
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
FingerprintJS is a good free starting point if you want to recognize returning browsers in a web app and can accept lower accuracy. Pick a commercial service or a different approach if you need reliable fraud prevention, strong resistance to spoofing, or clear privacy compliance.
Install options & downloads