mirror of
https://github.com/oven-sh/bun
synced 2026-02-14 12:51:54 +00:00
177 lines
4.4 KiB
Markdown
177 lines
4.4 KiB
Markdown
---
|
|
name: bun prune
|
|
---
|
|
|
|
The `bun prune` command removes extraneous packages from your project's `node_modules` directory. Extraneous packages are those that are installed but not declared as dependencies in your `package.json` or referenced in your lockfile.
|
|
|
|
```bash
|
|
$ bun prune
|
|
```
|
|
|
|
This command is useful for:
|
|
|
|
- Cleaning up packages that were manually installed but never added to `package.json`
|
|
- Removing leftover packages after removing dependencies
|
|
- Ensuring your `node_modules` directory only contains necessary packages
|
|
- Reducing disk space usage by removing unused packages
|
|
|
|
## How it works
|
|
|
|
`bun prune` analyzes your project's lockfile (`bun.lockb` or `bun.lock`) to determine which packages should be present in `node_modules`, then removes any packages that aren't referenced.
|
|
|
|
The command:
|
|
|
|
1. Reads your project's lockfile to identify legitimate packages
|
|
2. Scans the `node_modules` directory for installed packages
|
|
3. Removes any packages not found in the lockfile
|
|
4. Handles both regular packages (`package-name`) and scoped packages (`@scope/package-name`)
|
|
5. Reports the number of packages removed
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
# Remove extraneous packages
|
|
$ bun prune
|
|
|
|
# Show help
|
|
$ bun prune --help
|
|
```
|
|
|
|
## Examples
|
|
|
|
### Basic usage
|
|
|
|
```bash
|
|
$ bun prune
|
|
bun prune v1.2.21
|
|
|
|
Removing lodash
|
|
Removing @types/unused-package
|
|
Removed 2 extraneous packages
|
|
Pruned extraneous packages
|
|
```
|
|
|
|
### No extraneous packages
|
|
|
|
```bash
|
|
$ bun prune
|
|
bun prune v1.2.21
|
|
|
|
Pruned extraneous packages
|
|
```
|
|
|
|
### Missing lockfile
|
|
|
|
```bash
|
|
$ bun prune
|
|
bun prune v1.2.21
|
|
|
|
error: Lockfile not found
|
|
```
|
|
|
|
## When to use `bun prune`
|
|
|
|
### After removing dependencies
|
|
|
|
When you remove a dependency with `bun remove`, the package is removed from `package.json` and the lockfile, but may still exist in `node_modules`. Use `bun prune` to clean it up:
|
|
|
|
```bash
|
|
$ bun remove lodash
|
|
$ bun prune # Remove lodash from node_modules if still present
|
|
```
|
|
|
|
### After manual package installation
|
|
|
|
If you manually installed packages without adding them to `package.json`:
|
|
|
|
```bash
|
|
$ cd node_modules && npm install some-package # Manual install
|
|
$ bun prune # Will remove some-package since it's not in package.json
|
|
```
|
|
|
|
### Before deployment
|
|
|
|
Clean up your dependencies before deploying to ensure only necessary packages are included:
|
|
|
|
```bash
|
|
$ bun install
|
|
$ bun prune
|
|
$ bun run build
|
|
```
|
|
|
|
### Disk space cleanup
|
|
|
|
Remove unused packages to free up disk space:
|
|
|
|
```bash
|
|
$ bun prune
|
|
Removed 15 extraneous packages
|
|
# Freed up several MB of disk space
|
|
```
|
|
|
|
## Error handling
|
|
|
|
### Missing package.json
|
|
|
|
```bash
|
|
$ bun prune
|
|
error: No package.json was found for directory "/path/to/project"
|
|
|
|
Note: Run "bun init" to initialize a project
|
|
```
|
|
|
|
### Missing lockfile
|
|
|
|
```bash
|
|
$ bun prune
|
|
error: Lockfile not found
|
|
```
|
|
|
|
Run `bun install` first to generate a lockfile:
|
|
|
|
```bash
|
|
$ bun install
|
|
$ bun prune
|
|
```
|
|
|
|
### No node_modules directory
|
|
|
|
If `node_modules` doesn't exist, `bun prune` succeeds without doing anything:
|
|
|
|
```bash
|
|
$ rm -rf node_modules
|
|
$ bun prune
|
|
bun prune v1.2.21
|
|
|
|
Pruned extraneous packages
|
|
```
|
|
|
|
## Comparison with other package managers
|
|
|
|
| Command | Behavior |
|
|
| ------------ | --------------------------------------------------------------- |
|
|
| `npm prune` | Removes extraneous packages not in `package.json` dependencies |
|
|
| `pnpm prune` | Removes orphaned packages not referenced by any dependency tree |
|
|
| `bun prune` | Removes packages not referenced in the lockfile |
|
|
|
|
`bun prune` is most similar to `npm prune` but uses Bun's lockfile as the source of truth rather than just `package.json`.
|
|
|
|
## Flags
|
|
|
|
Currently, `bun prune` doesn't support additional flags beyond `--help`. The command operates on the current working directory and uses the default log level for output.
|
|
|
|
## Technical details
|
|
|
|
- **Lockfile dependency**: Requires a valid lockfile (`bun.lockb` or `bun.lock`)
|
|
- **Package detection**: Scans `node_modules` directory structure
|
|
- **Scope handling**: Properly handles scoped packages under `@scope/` directories
|
|
- **Safety**: Only removes packages not found in the lockfile
|
|
- **Performance**: Efficiently processes large `node_modules` directories
|
|
|
|
## Related commands
|
|
|
|
- [`bun install`](/docs/cli/install) - Install dependencies and generate lockfile
|
|
- [`bun remove`](/docs/cli/remove) - Remove dependencies from package.json
|
|
- [`bun add`](/docs/cli/add) - Add dependencies to package.json
|
|
- [`bun pm cache rm`](/docs/cli/pm#bun-pm-cache-rm) - Clear the global package cache
|