{"canonical_url":"https://engineer.company/glossary/package/","content_markdown":"# Package\n\n## What it is\n\nA package is the form in which software travels from the people who write it to the machines that\nrun it: the code, as an archive or a directory, together with a manifest giving its name, its\nversion and what else it needs in order to work. The plural is packages, and system documentation\noften says software package. Each ecosystem draws the edges in its own place. For npm, a package is\na file or directory described by a package.json file, and the npm documentation separates it from a\nmodule, anything Node.js can load with require() or import; only modules that carry a package.json\nare packages. Python uses the word for two things, and the\n[Python Packaging User Guide](https://packaging.python.org/) keeps them apart: an import package is\na directory of modules that code imports, while a distribution package\nis the versioned archive a user downloads and installs. In Rust, a package bundles one or more\ncrates with a Cargo.toml that says how to build them. On Debian, the unit is the binary package, the\n.deb file the system installs and tracks.\n\nA package is a unit of distribution, and it is easiest to define against its neighbours. A library\nis code; a package is how that code is shipped, and one library can reach users as an npm package, a\nPython wheel and a Debian package at once. A package manager is the program that reads manifests,\nfetches what they list and installs it all in a workable order: npm, pip, Cargo and apt. A registry\nor archive is where packages wait to be fetched, such as the npm registry, PyPI, crates.io or a\nDebian mirror. Language package managers install code for one project, usually into a directory\nbeside it. System package managers install software for the whole machine and record which package\nput each file where.\n\n## Why it matters\n\nThird-party code reaches a project in one of three ways: through a package manager, copied into the\nrepository with its licence and a checksum, which is called vendoring, or built from source. A\npackage manager is the usual choice for good reason. It resolves the whole tree of dependencies,\nupdates them with one command and records what it installed. The cost is trust: the project now\nrelies on every manifest in that tree and every registry it came from. Vendoring swaps that trust\nfor work, since the copied code changes only when someone copies a new version in on purpose.\nBuilding from source gives the most control and asks for the most upkeep.\n\nThe manifest is where most of the trade-offs show. It usually names a range of versions rather than\none; in npm, a caret range such as ^10.0.1 accepts any later release with the same major version.\nRanges let fixes arrive without anyone editing the file, and they also mean two installs a week\napart can produce different trees. A lock file closes that gap. npm writes package-lock.json to\ndescribe the exact tree it built so later installs reproduce it, Cargo writes Cargo.lock with the\nexact version of every dependency, and both expect the file to be committed. The manifest records\nwhat a project is willing to accept; the lock file records what it received.\n\nManifests also say how badly one package needs another. The Debian Policy Manual defines a ladder.\nDepends is absolute: the package is not configured until everything it depends on has been.\nRecommends is strong but not absolute, for packages that accompany this one in every installation\nexcept unusual ones. Suggests names packages that make it more useful, while installing without them\nis perfectly reasonable. An install that leaves out a recommended package is valid, and the software\ninside may still need that package for one of its jobs.\n\nEvery tool that reasons about packages trusts their metadata. A licence checker reads the declared\nlicence, often an SPDX expression such as MIT OR Apache-2.0, where OR offers a choice and AND\nrequires every licence at once. A vulnerability scanner matches declared names and versions against\npublished advisories. When a declaration is wrong, every tool that reads it is wrong in the same\nway, which is why the licence files inside a shipped package deserve a read of their own.\n\n## What it looks like in practice\n\nA hardening review of a production server found that its intrusion-banning jail had never banned\nanyone, and one of three separate causes was a package relationship. The ban action called a\npacket-filter program that the packaging lists as recommended rather than required, and the server\nhad been built without it. The jail started, counted failed logins and reached its decision every\ntime, then broke at the final step of applying the ban. The\n[review of three SSH protections](/portfolio/three-locks-on-the-door-none-of-them-locked/)\nfound it by inspecting the running system instead of the configuration files, and left a rule that\nevery security control is backed by an automated assertion, not a comment.\n\nA Rust core linked into a shipped application brings its whole dependency graph into the product,\n644 crates here, each with its own licence declaration. A dependency several layers down can move to\na copyleft licence from one version to the next, and the only trace would be a changed line in a\nlock file few people read. The\n[licence audit of 644 crates](/portfolio/know-the-licence-of-everything-you-ship/)\nruns on every build: it evaluates each crate's licence expression against an allow list, passes a\nchoice of licences when any one is allowed and a combination only when all are, and stops the build\non anything unmatched. To show the check can fire, it was broken deliberately twice, once by\nrewriting a crate's licence expression and once by moving the pinned core revision without\nregenerating the audit. The page states the limit plainly: the audit reads declared metadata, which\ncan be wrong, and it is not legal advice.\n\nThe company's own git forge was\n[installed from its vendor's own package source](/portfolio/your-code-on-your-own-hardware/)\nas a single program that the operating system keeps running. Adding a vendor's repository to a\nserver is a decision in its own right, because from then on routine updates install whatever that\nvendor publishes and signs.\n\nThis site itself needs no Node to run. Its package.json is marked private, which tells npm to refuse\nto publish it, lists development tools only, with caret ranges, and sits beside a committed\npackage-lock.json. Its pyproject.toml configures a linter, a spell checker and a type checker and\nhas no [project] or [build-system] table, since it describes no package to build. The icons are\nvendored, copied in with the upstream licence and a SHA-256 checksum for every file.\n\n## Where it goes wrong\n\n### A feature reports healthy and does nothing\n\nA service starts, logs that it is running and quietly skips one of its jobs every time. A program it\ncalls belongs to a recommended or suggested package, which the install was entitled to leave out.\nWhen a feature depends on an external program, check for it at start-up and stop with a clear error\nif it is missing, declare it as a hard requirement in your own deployment, and test the feature end\nto end on a server built like production.\n\n### Two machines install different code from the same manifest\n\nThe build passes on a laptop and breaks in continuous integration, or the reverse, with no change to\nthe project's own code. The manifest names version ranges, the lock file was never committed, and a\ndependency published a release between the two installs. Commit the lock file, install from it in\nautomation with commands that refuse to change it, such as npm ci or cargo build --locked, and\nupdate it as a separate, reviewed change.\n\n### A licence changes inside a familiar dependency\n\nA product that passed a licence review last year now ships code under terms nobody agreed to, while\nits list of dependencies looks the same. An existing dependency changed its licence between\nversions, and a routine update pulled the new version in through the lock file. Check declared\nlicences against an explicit allow list on every build, so the change stops the build on the day it\narrives.\n\n## Further reading\n\n- [npm Docs: About packages and modules](https://docs.npmjs.com/about-packages-and-modules) — npm's\n  own definition of a package, and why a module is not always one.\n- [Debian Policy Manual: Declaring relationships between packages](https://www.debian.org/doc/debian-policy/ch-relationships.html)\n  — Depends, Recommends, Suggests and the other fields, and what a package manager does with each.\n- [Python Packaging User Guide: Writing your pyproject.toml](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/)\n  — the three tables of pyproject.toml and the metadata a Python distribution package declares.\n- [The Cargo Book: Cargo.toml vs Cargo.lock](https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html)\n  — why the manifest describes what a project accepts, the lock file records exact versions, and\n  when to commit it.\n- [SPDX Specification 2.3.1: License expressions](https://spdx.github.io/spdx-spec/v2.3.1/SPDX-license-expressions/)\n  — the syntax packages use to declare one licence, a choice of several or a set that applies\n  together.\n\n\u003chttps://engineer.company/glossary/package/\u003e\n","date_modified":"2026-10-20T21:59:50Z","description":"What a software package contains, how manifests, lock files and declared dependencies decide what gets installed, and why a clean install can still be broken.","formats":{"gemtext":"https://engineer.company/glossary/package/index.gmi","gopher":"https://engineer.company/glossary/package/gophermap","html":"https://engineer.company/glossary/package/","json":"https://engineer.company/glossary/package/index.json","markdown":"https://engineer.company/glossary/package/index.md","pdf":"https://engineer.company/glossary/package/index.pdf"},"kind":"page","language":"en","title":"What is a package?","url":"https://engineer.company/glossary/package/","version":1}