{"id":48753,"library":"node-llama-cpp","title":"node-llama-cpp","description":"Run large language models (LLMs) locally from Node.js using llama.cpp bindings. Version 3.18.1 provides pre-built binaries for macOS, Linux, and Windows (Metal, CUDA, Vulkan) with automatic fallback to source build via cmake (no node-gyp or Python required). Supports JSON schema enforcement, function calling, embedding, reranking, and chat sessions. Full TypeScript types included. Active development with frequent releases synced to upstream llama.cpp. Key differentiator: zero-config GPU acceleration and safe token injection prevention.","status":"active","version":"3.18.1","language":"javascript","source_language":"en","source_url":"https://github.com/withcatai/node-llama-cpp","tags":["javascript","llama","llama-cpp","llama.cpp","bindings","ai","cmake","cmake-js","prebuilt-binaries","typescript"],"install":[{"cmd":"npm install node-llama-cpp","lang":"bash","label":"npm"},{"cmd":"yarn add node-llama-cpp","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-llama-cpp","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency: >=5.0.0 for TypeScript types and compilation support","package":"typescript","optional":true}],"imports":[{"note":"Package is ESM-only; require() fails unless using dynamic import()","wrong":"const getLlama = require('node-llama-cpp').getLlama","symbol":"getLlama","correct":"import { getLlama } from 'node-llama-cpp'"},{"note":"Named export, not default. Subpath imports are not supported.","wrong":"import LlamaChatSession from 'node-llama-cpp/LlamaChatSession'","symbol":"LlamaChatSession","correct":"import { LlamaChatSession } from 'node-llama-cpp'"},{"note":"Default export does not exist; must use named import.","wrong":"import getLlama from 'node-llama-cpp'","symbol":"getLlama","correct":"import { getLlama } from 'node-llama-cpp'"}],"quickstart":{"code":"import { fileURLToPath } from 'url';\nimport path from 'path';\nimport { getLlama, LlamaChatSession } from 'node-llama-cpp';\n\nconst __dirname = path.dirname(fileURLToPath(import.meta.url));\n\nconst llama = await getLlama();\nconst model = await llama.loadModel({\n  modelPath: path.join(__dirname, 'model.gguf')\n});\nconst context = await model.createContext();\nconst session = new LlamaChatSession({ contextSequence: context.getSequence() });\n\nconst response = await session.prompt('What is the capital of France?');\nconsole.log(response);","lang":"typescript","description":"Loads a GGUF model and performs a simple chat prompt, showing file setup, model loading, and session creation."},"warnings":[{"fix":"Use import syntax or dynamic import() inside CommonJS modules.","message":"Package is ESM-only since v3.0 - CommonJS require() will not work.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade Node.js to a version >=20.","message":"Node.js >=20.0.0 required - earlier versions cause runtime errors.","severity":"breaking","affected_versions":"all"},{"fix":"Use llama.loadModel() instead of llama.load().","message":"LlamaModel.load() is deprecated in favor of LlamaModel.loadModel().","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Ensure cmake and build tools are installed, or set NODE_LLAMA_CPP_SKIP_DOWNLOAD=true to force source build.","message":"Pre-built binaries may fail on uncommon architectures; build from source via cmake fallback.","severity":"gotcha","affected_versions":"all"},{"fix":"Use path.resolve(__dirname, 'model.gguf') or path.join with __dirname.","message":"Model path must be absolute; relative paths may not resolve correctly.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"search_vec":"'3.18.1':17 'acceler':76 'activ':61 'ai':89 'automat':32 'binari':22,96 'bind':15,88 'build':36 'built':21 'call':51 'chat':55 'cmake':38,90,92 'cmake-j':91 'config':74 'cpp':4,86 'cuda':29 'develop':62 'differenti':71 'embed':52 'enforc':49 'fallback':33 'frequent':64 'full':57 'function':50 'gpu':75 'gyp':42 'includ':60 'inject':80 'javascript':82 'js':93 'json':47 'key':70 'languag':7 'larg':6 'linux':25 'llama':3,83,85 'llama-cpp':84 'llama.cpp':14,69,87 'llms':9 'local':10 'maco':24 'metal':28 'model':8 'node':2,41 'node-gyp':40 'node-llama-cpp':1 'node.js':12 'pre':20 'pre-built':19 'prebuilt':95 'prebuilt-binari':94 'prevent':81 'provid':18 'python':44 'releas':65 'requir':45 'rerank':53 'run':5 'safe':78 'schema':48 'session':56 'sourc':35 'support':46 'sync':66 'token':79 'type':59 'typescript':58,97 'upstream':68 'use':13 'version':16 'via':37 'vulkan':30 'window':27 'zero':73 'zero-config':72","created_at":"2026-06-07T16:58:16.997982+00:00","updated_at":"2026-06-07T16:58:16.997982+00:00","problems":[{"fix":"Switch to import syntax or use dynamic import(): const { getLlama } = await import('node-llama-cpp');","cause":"Using require() to load an ESM-only package.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module not supported"},{"fix":"Use import { getLlama } from 'node-llama-cpp' instead of import getLlama from 'node-llama-cpp'.","cause":"Named import misused as default import.","error":"TypeError: getLlama is not a function"},{"fix":"Use an absolute path: path.resolve(__dirname, 'model.gguf').","cause":"Relative model path resolved incorrectly from process.cwd().","error":"Error: Model file not found at /some/path"},{"fix":"Reinstall package, force source build: npm rebuild node-llama-cpp --build-from-source","cause":"Pre-built binary mismatch or missing cmake build.","error":"Error: Dynamic library not found: libllama.dylib"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://node-llama-cpp.withcat.ai","github":"https://github.com/withcatai/node-llama-cpp","docs":null,"changelog":null,"pypi":null,"npm":"node-llama-cpp","openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}