1--- 2title: npm-link 3section: 1 4description: Symlink a package folder 5--- 6 7### Synopsis 8 9```bash 10npm link [<package-spec>] 11 12alias: ln 13``` 14 15### Description 16 17This is handy for installing your own stuff, so that you can work on it and 18test iteratively without having to continually rebuild. 19 20Package linking is a two-step process. 21 22First, `npm link` in a package folder with no arguments will create a 23symlink in the global folder `{prefix}/lib/node_modules/<package>` that 24links to the package where the `npm link` command was executed. It will 25also link any bins in the package to `{prefix}/bin/{name}`. Note that 26`npm link` uses the global prefix (see `npm prefix -g` for its value). 27 28Next, in some other location, `npm link package-name` will create a 29symbolic link from globally-installed `package-name` to `node_modules/` of 30the current folder. 31 32Note that `package-name` is taken from `package.json`, _not_ from the 33directory name. 34 35The package name can be optionally prefixed with a scope. See 36[`scope`](/using-npm/scope). The scope must be preceded by an @-symbol and 37followed by a slash. 38 39When creating tarballs for `npm publish`, the linked packages are 40"snapshotted" to their current state by resolving the symbolic links, if 41they are included in `bundleDependencies`. 42 43For example: 44 45```bash 46cd ~/projects/node-redis # go into the package directory 47npm link # creates global link 48cd ~/projects/node-bloggy # go into some other package directory. 49npm link redis # link-install the package 50``` 51 52Now, any changes to `~/projects/node-redis` will be reflected in 53`~/projects/node-bloggy/node_modules/node-redis/`. Note that the link 54should be to the package name, not the directory name for that package. 55 56You may also shortcut the two steps in one. For example, to do the 57above use-case in a shorter way: 58 59```bash 60cd ~/projects/node-bloggy # go into the dir of your main project 61npm link ../node-redis # link the dir of your dependency 62``` 63 64The second line is the equivalent of doing: 65 66```bash 67(cd ../node-redis; npm link) 68npm link redis 69``` 70 71That is, it first creates a global link, and then links the global 72installation target into your project's `node_modules` folder. 73 74Note that in this case, you are referring to the directory name, 75`node-redis`, rather than the package name `redis`. 76 77If your linked package is scoped (see [`scope`](/using-npm/scope)) your 78link command must include that scope, e.g. 79 80```bash 81npm link @myorg/privatepackage 82``` 83 84### Caveat 85 86Note that package dependencies linked in this way are _not_ saved to 87`package.json` by default, on the assumption that the intention is to have 88a link stand in for a regular non-link dependency. Otherwise, for example, 89if you depend on `redis@^3.0.1`, and ran `npm link redis`, it would replace 90the `^3.0.1` dependency with `file:../path/to/node-redis`, which you 91probably don't want! Additionally, other users or developers on your 92project would run into issues if they do not have their folders set up 93exactly the same as yours. 94 95If you are adding a _new_ dependency as a link, you should add it to the 96relevant metadata by running `npm install <dep> --package-lock-only`. 97 98If you _want_ to save the `file:` reference in your `package.json` and 99`package-lock.json` files, you can use `npm link <dep> --save` to do so. 100 101### Workspace Usage 102 103`npm link <pkg> --workspace <name>` will link the relevant package as a 104dependency of the specified workspace(s). Note that It may actually be 105linked into the parent project's `node_modules` folder, if there are no 106conflicting dependencies. 107 108`npm link --workspace <name>` will create a global link to the specified 109workspace(s). 110 111### Configuration 112 113#### `save` 114 115* Default: `true` unless when using `npm update` where it defaults to `false` 116* Type: Boolean 117 118Save installed packages to a `package.json` file as dependencies. 119 120When used with the `npm rm` command, removes the dependency from 121`package.json`. 122 123Will also prevent writing to `package-lock.json` if set to `false`. 124 125 126 127#### `save-exact` 128 129* Default: false 130* Type: Boolean 131 132Dependencies saved to package.json will be configured with an exact version 133rather than using npm's default semver range operator. 134 135 136 137#### `global` 138 139* Default: false 140* Type: Boolean 141 142Operates in "global" mode, so that packages are installed into the `prefix` 143folder instead of the current working directory. See 144[folders](/configuring-npm/folders) for more on the differences in behavior. 145 146* packages are installed into the `{prefix}/lib/node_modules` folder, instead 147 of the current working directory. 148* bin files are linked to `{prefix}/bin` 149* man pages are linked to `{prefix}/share/man` 150 151 152 153#### `install-strategy` 154 155* Default: "hoisted" 156* Type: "hoisted", "nested", "shallow", or "linked" 157 158Sets the strategy for installing packages in node_modules. hoisted 159(default): Install non-duplicated in top-level, and duplicated as necessary 160within directory structure. nested: (formerly --legacy-bundling) install in 161place, no hoisting. shallow (formerly --global-style) only install direct 162deps at top-level. linked: (experimental) install in node_modules/.store, 163link in place, unhoisted. 164 165 166 167#### `legacy-bundling` 168 169* Default: false 170* Type: Boolean 171* DEPRECATED: This option has been deprecated in favor of 172 `--install-strategy=nested` 173 174Instead of hoisting package installs in `node_modules`, install packages in 175the same manner that they are depended on. This may cause very deep 176directory structures and duplicate package installs as there is no 177de-duplicating. Sets `--install-strategy=nested`. 178 179 180 181#### `global-style` 182 183* Default: false 184* Type: Boolean 185* DEPRECATED: This option has been deprecated in favor of 186 `--install-strategy=shallow` 187 188Only install direct dependencies in the top level `node_modules`, but hoist 189on deeper dependencies. Sets `--install-strategy=shallow`. 190 191 192 193#### `strict-peer-deps` 194 195* Default: false 196* Type: Boolean 197 198If set to `true`, and `--legacy-peer-deps` is not set, then _any_ 199conflicting `peerDependencies` will be treated as an install failure, even 200if npm could reasonably guess the appropriate resolution based on non-peer 201dependency relationships. 202 203By default, conflicting `peerDependencies` deep in the dependency graph will 204be resolved using the nearest non-peer dependency specification, even if 205doing so will result in some packages receiving a peer dependency outside 206the range set in their package's `peerDependencies` object. 207 208When such an override is performed, a warning is printed, explaining the 209conflict and the packages involved. If `--strict-peer-deps` is set, then 210this warning is treated as a failure. 211 212 213 214#### `package-lock` 215 216* Default: true 217* Type: Boolean 218 219If set to false, then ignore `package-lock.json` files when installing. This 220will also prevent _writing_ `package-lock.json` if `save` is true. 221 222 223 224#### `omit` 225 226* Default: 'dev' if the `NODE_ENV` environment variable is set to 227 'production', otherwise empty. 228* Type: "dev", "optional", or "peer" (can be set multiple times) 229 230Dependency types to omit from the installation tree on disk. 231 232Note that these dependencies _are_ still resolved and added to the 233`package-lock.json` or `npm-shrinkwrap.json` file. They are just not 234physically installed on disk. 235 236If a package type appears in both the `--include` and `--omit` lists, then 237it will be included. 238 239If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment 240variable will be set to `'production'` for all lifecycle scripts. 241 242 243 244#### `include` 245 246* Default: 247* Type: "prod", "dev", "optional", or "peer" (can be set multiple times) 248 249Option that allows for defining which types of dependencies to install. 250 251This is the inverse of `--omit=<type>`. 252 253Dependency types specified in `--include` will not be omitted, regardless of 254the order in which omit/include are specified on the command-line. 255 256 257 258#### `ignore-scripts` 259 260* Default: false 261* Type: Boolean 262 263If true, npm does not run scripts specified in package.json files. 264 265Note that commands explicitly intended to run a particular script, such as 266`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script` 267will still run their intended script if `ignore-scripts` is set, but they 268will *not* run any pre- or post-scripts. 269 270 271 272#### `audit` 273 274* Default: true 275* Type: Boolean 276 277When "true" submit audit reports alongside the current npm command to the 278default registry and all registries configured for scopes. See the 279documentation for [`npm audit`](/commands/npm-audit) for details on what is 280submitted. 281 282 283 284#### `bin-links` 285 286* Default: true 287* Type: Boolean 288 289Tells npm to create symlinks (or `.cmd` shims on Windows) for package 290executables. 291 292Set to false to have it not do this. This can be used to work around the 293fact that some file systems don't support symlinks, even on ostensibly Unix 294systems. 295 296 297 298#### `fund` 299 300* Default: true 301* Type: Boolean 302 303When "true" displays the message at the end of each `npm install` 304acknowledging the number of dependencies looking for funding. See [`npm 305fund`](/commands/npm-fund) for details. 306 307 308 309#### `dry-run` 310 311* Default: false 312* Type: Boolean 313 314Indicates that you don't want npm to make any changes and that it should 315only report what it would have done. This can be passed into any of the 316commands that modify your local installation, eg, `install`, `update`, 317`dedupe`, `uninstall`, as well as `pack` and `publish`. 318 319Note: This is NOT honored by other network related commands, eg `dist-tags`, 320`owner`, etc. 321 322 323 324#### `workspace` 325 326* Default: 327* Type: String (can be set multiple times) 328 329Enable running a command in the context of the configured workspaces of the 330current project while filtering by running only the workspaces defined by 331this configuration option. 332 333Valid values for the `workspace` config are either: 334 335* Workspace names 336* Path to a workspace directory 337* Path to a parent workspace directory (will result in selecting all 338 workspaces within that folder) 339 340When set for the `npm init` command, this may be set to the folder of a 341workspace which does not yet exist, to create the folder and set it up as a 342brand new workspace within the project. 343 344This value is not exported to the environment for child processes. 345 346#### `workspaces` 347 348* Default: null 349* Type: null or Boolean 350 351Set to true to run the command in the context of **all** configured 352workspaces. 353 354Explicitly setting this to false will cause commands like `install` to 355ignore workspaces altogether. When not set explicitly: 356 357- Commands that operate on the `node_modules` tree (install, update, etc.) 358will link workspaces into the `node_modules` folder. - Commands that do 359other things (test, exec, publish, etc.) will operate on the root project, 360_unless_ one or more workspaces are specified in the `workspace` config. 361 362This value is not exported to the environment for child processes. 363 364#### `include-workspace-root` 365 366* Default: false 367* Type: Boolean 368 369Include the workspace root when workspaces are enabled for a command. 370 371When false, specifying individual workspaces via the `workspace` config, or 372all workspaces via the `workspaces` flag, will cause npm to operate only on 373the specified workspaces, and not on the root project. 374 375This value is not exported to the environment for child processes. 376 377#### `install-links` 378 379* Default: false 380* Type: Boolean 381 382When set file: protocol dependencies will be packed and installed as regular 383dependencies instead of creating a symlink. This option has no effect on 384workspaces. 385 386 387 388### See Also 389 390* [package spec](/using-npm/package-spec) 391* [npm developers](/using-npm/developers) 392* [package.json](/configuring-npm/package-json) 393* [npm install](/commands/npm-install) 394* [npm folders](/configuring-npm/folders) 395* [npm config](/commands/npm-config) 396* [npmrc](/configuring-npm/npmrc) 397