Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 39 ยท Package Manager and Scripts

Installing and Adding Packages

Use bun install, add, remove, update and outdated to manage npm packages - version ranges, dev and peer dependencies, git and local packages, global installs, production installs and why Bun is fast.

Bun's package manager is compatible with npm's registry and package.json, but much faster. You can use it in any Node.js project, even if you never run your code with Bun. This lesson covers the everyday commands: installing everything, adding and removing packages, choosing versions, dependency types, installing from git or disk, global tools, and what makes it quick.

Commands in this lesson are shell commands, shown read-only. The sandboxed page cannot install packages, but a runnable stand-in shows how version ranges behave.

bun install

In a folder with a package.json:

Terminal
bun install

Bun reads the dependencies and devDependencies, resolves every version (including each package's own dependencies), downloads what is missing into a global cache, and fills the local node_modules folder. It writes or updates bun.lock. If a lockfile already exists, Bun follows it, so the same versions install on every machine.

Typical output is a short summary like + [email protected] and 42 packages installed [380.00ms]. A repeat install with a warm cache often takes tens of milliseconds.

Useful flags:

Flag Purpose
--production Skip devDependencies (for deploy images).
--frozen-lockfile Fail if package.json and bun.lock disagree; never edit the lockfile. Use in CI.
--dry-run Show what would happen without changing anything.
--force Re-download and re-link everything.
--ignore-scripts Do not run lifecycle scripts.
--no-save Do not write package.json or the lockfile.
--verbose / --silent More or less output.

bun ci is shorthand for bun install --frozen-lockfile, similar to npm ci.

bun add

Terminal
bun add zod                 # latest, saved as "^x.y.z" in dependencies
bun add zod@3.23.8          # a specific version
bun add zod@latest          # explicit tag
bun add "zod@^3.20"         # a range
bun add -d typescript       # devDependencies (--dev)
bun add -E hono             # exact version, no caret (--exact)
bun add --optional sharp    # optionalDependencies
bun add --peer react        # peerDependencies
bun add -g cowsay           # global install

After bun add zod, package.json gains "zod": "^3.25.0" (the version number is whatever is newest at that moment), and bun.lock records the exact resolved version. The caret ^ means "compatible with 3.x.y at or above this version".

Remove packages with:

Terminal
bun remove zod

That edits package.json, the lockfile and node_modules.

Understanding version ranges

Semantic versioning splits a version into major.minor.patch. Ranges in package.json say how much change you accept:

Range Allows Example match for 1.4.2 base
1.4.2 exactly this version 1.4.2
^1.4.2 same major, at least this 1.4.2 to 1.x.y (not 2.0.0)
~1.4.2 same minor, at least this patch 1.4.2 to 1.4.x
>=1.4.0 <2 an explicit range 1.9.9
* or latest anything newest any

^ is the default because patch and minor releases should not break you. The lockfile pins what is actually installed, so ranges only matter when you run bun update or add the package fresh.

Here is a small runnable stand-in that implements the caret and tilde rules, to see how a range selects among released versions:

Node.js Stand-in: caret and tilde ranges (runs on Node 24)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Real tools handle pre-release tags and 0.x rules too (^0.2.3 only allows 0.2.x), but the idea is the same.

Dependency types

JSON
{
  "dependencies": { "hono": "^4.6.0" },
  "devDependencies": { "typescript": "^5.6.0", "@types/bun": "latest" },
  "peerDependencies": { "react": ">=18" },
  "optionalDependencies": { "fsevents": "^2.3.0" }
}
  • dependencies: needed at run time. Installed in production.
  • devDependencies: only for development (compilers, test tools, type packages).
  • peerDependencies: "the host project must provide this". Bun installs peers automatically when none is present, which npm also does in recent versions.
  • optionalDependencies: install failures are tolerated (platform-specific add-ons).

Put each package where it belongs; a wrong devDependencies entry is a classic reason a deploy fails with "module not found" after bun install --production.

Updating

Terminal
bun outdated          # table: current, update (within range), latest
bun update            # newest versions that still satisfy package.json ranges
bun update zod        # just one package
bun update --latest   # ignore ranges, move to the newest version and rewrite package.json
bun update -i         # interactive picker

bun outdated is a good weekly habit. bun update --latest can cross major versions, so run your tests afterwards.

Other sources for packages

Terminal
bun add github:user/repo               # a GitHub repo (default branch)
bun add github:user/repo#v1.2.0        # a tag or commit
bun add git+https://example.com/x.git  # a git URL
bun add ./libs/shared                  # a local folder
bun add ./pkg-1.0.0.tgz                # a tarball
bun add https://example.com/pkg.tgz    # a remote tarball

These show up in package.json as the URL or file: path. They are handy for forks and unreleased fixes, but pin a commit or tag so installs stay reproducible.

Linking local packages

When you develop a library and want to try it in an app without publishing:

Terminal
cd ~/libs/my-lib && bun link          # register the package
cd ~/apps/my-app && bun link my-lib   # use it here

The app's node_modules/my-lib now points at your working copy. For several packages in one repo, workspaces are usually better; see Workspaces and Catalogs.

Global packages

Terminal
bun add -g typescript prettier
bun pm ls -g

Global binaries go to ~/.bun/bin, which the installer already added to PATH. Prefer project-local installs plus bunx or scripts, so every developer uses the same tool version.

Why is it fast?

  • Native code. The resolver, tarball extractor and file linker are compiled Zig, with no JavaScript start-up cost.
  • One global cache. Packages are downloaded once and reused across projects at ~/.bun/install/cache.
  • Hardlinks or copy-on-write. Instead of copying files, Bun creates links to the cache (clonefile on macOS, hardlinks on Linux), which costs almost no disk or time.
  • Parallel work. Many downloads and file operations run at once, with minimal syscalls.
  • Binary-friendly metadata. Registry responses are parsed once and cached.

You can switch the file-copy method with --backend (hardlink, clonefile, copyfile, symlink); the defaults are right for most systems. On filesystems that do not support hardlinks across volumes (the cache on another drive), Bun falls back to copying and warns you, which is slower but correct.

flowchart LR
  A["package.json + bun.lock"] --> B["Resolve versions"]
  B --> C{"In global cache?"}
  C -- no --> D["Download tarball"]
  C -- yes --> E["Reuse"]
  D --> E
  E --> F["Link into node_modules"]

A warm install skips the download and only links files, which is why it is so quick.

Common mistakes

  • Mixing lockfiles. Keep only bun.lock once you switch; delete package-lock.json, yarn.lock or pnpm-lock.yaml, or Bun and npm will fight.
  • Editing node_modules. Changes vanish on the next install. Use patches instead.
  • Forgetting -d. Adding TypeScript or test tools as regular dependencies bloats production installs.
  • Running bun install without committing the lockfile. Always commit bun.lock.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command installs a package as a development dependency?

    bun add -d (or --dev) writes to devDependencies.
  2. 2. What does ^1.4.2 allow?

    The caret allows updates that do not change the major version.
  3. 3. Which command should CI use so that a mismatch between package.json and bun.lock fails the build?

    --frozen-lockfile (or bun ci) installs exactly what the lockfile says and fails if it is out of date.
  4. 4. Why is a warm bun install so fast?

    The cache avoids downloads and hardlinks or clonefile avoid copying.

Summary

  • bun install installs everything; bun add and bun remove change dependencies; bun update and bun outdated manage upgrades.
  • Use -d for dev tools, --exact for pinned versions, --production and --frozen-lockfile for deployments.
  • Version ranges (^, ~, exact) say how much change you accept; the lockfile pins what is installed.
  • Packages can come from the registry, git, tarballs or local folders; bun link connects local libraries.
  • Bun is fast thanks to native code, a shared cache, links instead of copies and parallelism.

Next: package.json, the Lockfile and the Cache