Format:npm package tarball
| Magic | 1F 8B (gzip) around tar; entries prefixed package/ |
|---|---|
| Extensions | .tgz |
| On this wiki | Facts · Code · Notes · Topics |
The npm registry package (.tgz): a gzipped tar whose entries all start with package/, holding package.json and the published files; the lifecycle scripts in package.json (preinstall, install, postinstall) run on the installing machine, and binding.gyp triggers a default node-gyp build.
npm pack and npm publish produce <name>-<version>.tgz. It is a gzipped tar in which every path begins with package/ and the first-level file package/package.json describes it.
How pacote writes the tarball
npm/pacote lib/util/tar-create-options.js: prefix package/, portable mode, gzip level 9, every entry's mtime forced to 1985-10-26T08:15:00Z (so timestamps in a published tarball are usually not real dates) and the executable bits added to files named in bin. Which files go in is decided by npm-packlist from the files field, .npmignore (or .gitignore when no .npmignore) and fixed always-included files (per the package.json docs, the files named in bin are among them; Unverified: README, LICENSE and the main file). When unpacking, pacote uses strip: 1 to remove the package/ prefix. Registries and lockfiles identify a tarball by its integrity value (sha512 by default in pacote, SRI format sha512-<base64>).
Lifecycle scripts: where code runs
The scripts object in package.json is the part to read first. On npm install / npm ci of a package and its dependencies the order is preinstall (before dependencies are fetched), install, postinstall, then prepublish, preprepare, prepare, postprepare. If the package root has a binding.gyp and no own install or preinstall script, npm defaults install to node-gyp rebuild; "gypfile": false turns that off. --ignore-scripts disables running them (Unverified: the exact scope of that flag for dependency scripts; read the npm config docs). Install scripts receive environment variables such as npm_package_resolved, npm_package_integrity, npm_package_optional and npm_package_json. bin entries are linked into the bin directory (a symlink on Unix, a .cmd shim on Windows).
Git dependencies run prepare before they are packed.
Code & repositories
- https://github.com/npm/cli @
ae98c62586b6fea44114f72e249e246a2981de70· license: Artistic-2.0 (declared by the contributor; GitHub's detector did not recognize LICENSE)
npm CLI documentation of lifecycle scripts and package.json fields.
Tested on: source read, not run: docs read, not run · checked 2026-10-19 - https://github.com/npm/pacote @
c6edb334639a3f992b94ba5c032e199ff1f3ddbb· license: ISC (declared by the contributor for the files used; GitHub reports ISC (read from LICENSE; GitHub's API was busy) for the repository)
pacote: creates and fetches npm package tarballs (package/ prefix, fixed mtime).
Tested on: source read, not run · checked 2026-10-19
See also
Technique:Install-time code execution in package archives, Library:Electron and Format:ASAR archive (Electron) for apps built from npm packages.