Guide · Open source
How to use face-api.js: load models, detect faces and landmarks
Updated · written with AI from the project's own documentation and checked against our catalogue data
face-api.js is a JavaScript library for finding faces in images and video and reading features from them, such as landmarks, expressions, and estimated age and gender. It runs on top of tensorflow.js, so it works in a web browser or in Node.js. This guide shows you how to install it, load the models it needs, and run face detection on an image or element.
face-api.jsjustadudewhohacks/face-api.js · ★ 18k · MIT Install options & downloads Quick start
- 1Install the package. Run npm i face-api.js in your project. Node.js and npm are the prerequisites.
- 2Copy the model files. Place each model's manifest.json and shard files together in a folder such as public/models.
- 3Load a network. Call faceapi.nets.ssdMobilenetv1.loadFromUri('/models') in the browser, or loadFromDisk in Node.js.
- 4Pass an input. Give detectAllFaces an img, video or canvas element, or the id of that element.
- 5Read the results. Use the returned array of detections, or detectSingleFace for only the most confident face.
- 6Add more analysis. Load and chain the landmark, expression, or age and gender networks as needed, following the API docs.
Install face-api.js with npm
For a browser project or a Node.js project, install the package from npm. The README lists Node.js and npm as the prerequisites for the package-manager route.
For browser use you can instead include the latest script from the dist folder of the repository.
npm i face-api.jsLoad the models
face-api.js does not work until you load the neural network models. The manifest.json file and the weight shard files of a model must sit in the same directory, reachable under the same route. The README's example assumes the models are in public/models.
All loaded networks are exported via faceapi.nets. In Node.js you can load models from disk instead of a URL.
- Browser: await faceapi.nets.ssdMobilenetv1.loadFromUri('/models')
- Node.js: await faceapi.nets.ssdMobilenetv1.loadFromDisk('./models')
- Other nets such as faceLandmark68Net and faceRecognitionNet are loaded the same way
await faceapi.nets.ssdMobilenetv1.loadFromUri('/models')Detect faces in an image or video
The input can be an HTML img, video or canvas element, or the id of that element. detectAllFaces returns every face it finds. detectSingleFace returns the face with the highest confidence score, or undefined if none is found.
By default both functions use the SSD Mobilenet V1 face detector. You can pick another detector by passing its options object, such as TinyFaceDetectorOptions.
- detectAllFaces returns an array of detections
- detectSingleFace returns one detection or undefined
- Pass new faceapi.SsdMobilenetv1Options() or new faceapi.TinyFaceDetectorOptions() to choose the detector
const input = document.getElementById('myImg')
const detections = await faceapi.detectAllFaces(input)
const detection = await faceapi.detectSingleFace(input)Add landmarks, expressions and age or gender
After face detection you can chain further analysis. The README describes 68 point face landmarks, face recognition, expression recognition, and age estimation with gender recognition as features of the library.
The README's Features section shows examples of each, but the truncated source does not include the full chaining syntax for every feature. Check the API documentation linked from the README for the exact calls.
- Face landmark detection: 68 points per detected face
- Face expression recognition
- Age estimation and gender recognition
- Face recognition
Use face-api.js in Node.js
In Node.js, face-api.js needs browser objects such as HTMLImageElement, HTMLCanvasElement and ImageData. The README suggests the node-canvas package to provide them, then monkey patches the environment with faceapi.env.monkeyPatch.
The README also recommends @tensorflow/tfjs-node. It is not required, but it speeds things up considerably by binding to the native TensorFlow C++ library. Python is noted as required for it in the example.
- Install face-api.js, canvas and @tensorflow/tfjs-node together
- Alternatively, build your own tensors from image data and pass them as inputs
npm i face-api.js canvas @tensorflow/tfjs-nodeRun the example projects
The repository includes browser and Node.js example projects. To run the browser examples, you move into the examples folder, install, and start the server, then open the local address the README gives. For Node.js, you run example files with ts-node or compile them with tsc and run them with node.
- Browser examples are served at http://localhost:3000/
- Node.js example file used in the README: faceDetection.ts
cd face-api.js/examples/examples-browser
npm i
npm startWhat people use it for
- Detecting faces in a photo on a web page
- Building a webcam demo that tracks faces or expressions
- Running server-side face detection in a Node.js script
- Learning how face recognition works in JavaScript
Frequently asked questions
Is face-api.js free to use?
face-api.js is released under the MIT licence, as listed in the repository. Check the licence file in the repository for the full terms before using it in a product.
Do I need Node.js to use face-api.js?
No. The library can run in a web browser by including the script from the dist folder or installing it with npm. Node.js is needed when you want to run it server-side or use the npm install route.
Why does face-api.js need model files?
The face detection and analysis networks are loaded as manifest.json files plus weight shards. You must copy them to a folder your app can reach, then load them with loadFromUri or loadFromDisk.
How do I use face-api.js in Node.js?
Install face-api.js with canvas and @tensorflow/tfjs-node, then patch the environment with the canvas Canvas, Image and ImageData classes using faceapi.env.monkeyPatch. The README says tfjs-node is optional but speeds things up.
What are alternatives to face-api.js?
The repository compares it with MediaPipe, OpenCV.js, tracking.js and face-recognition for Node.js. Pick based on whether you need browser use, Node.js use, or specific features.
Is face-api.js suitable for large-scale face identification?
The README does not claim this. For identifying faces at large scale, a dedicated server-side system is likely a better fit than a browser-focused library.
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
face-api.js suits web developers and learners who want face detection, landmarks, expressions or age and gender estimation in the browser or Node.js with little machine learning code. Teams that need guaranteed accuracy, a commercially supported product, the latest research models, or large-scale face identification should look at other options such as MediaPipe or a dedicated server-side system.
Install options & downloads