1---
2name: pnpm-aliases
3description: Install packages under custom names for versioning, forks, or alternatives
4---
5 
6# pnpm Aliases
7 
8pnpm supports package aliases using the `npm:` protocol. This lets you install packages under different names, use multiple versions of the same package, or substitute packages.
9 
10## Basic Syntax
11 
12```bash
13pnpm add <alias>@npm:<package>@<version>
14```
15 
16In `package.json`:
17```json
18{
19  "dependencies": {
20    "<alias>": "npm:<package>@<version>"
21  }
22}
23```
24 
25## Use Cases
26 
27### Multiple Versions of Same Package
28 
29Install different versions side by side:
30 
31```json
32{
33  "dependencies": {
34    "lodash3": "npm:lodash@3",
35    "lodash4": "npm:lodash@4"
36  }
37}
38```
39 
40Usage:
41```js
42import lodash3 from 'lodash3'
43import lodash4 from 'lodash4'
44```
45 
46### Replace Package with Fork
47 
48Substitute a package with a fork or alternative:
49 
50```json
51{
52  "dependencies": {
53    "original-pkg": "npm:my-fork@^1.0.0"
54  }
55}
56```
57 
58All imports of `original-pkg` will resolve to `my-fork`.
59 
60### Replace Deprecated Package
61 
62```json
63{
64  "dependencies": {
65    "request": "npm:@cypress/request@^3.0.0"
66  }
67}
68```
69 
70### Scoped to Unscoped (or vice versa)
71 
72```json
73{
74  "dependencies": {
75    "vue": "npm:@anthropic/vue@^3.0.0",
76    "@myorg/utils": "npm:lodash@^4.17.21"
77  }
78}
79```
80 
81## CLI Usage
82 
83### Add with alias
84 
85```bash
86# Add lodash under alias
87pnpm add lodash4@npm:lodash@4
88 
89# Add fork as original name
90pnpm add request@npm:@cypress/request
91```
92 
93### Add multiple versions
94 
95```bash
96pnpm add react17@npm:react@17 react18@npm:react@18
97```
98 
99## With TypeScript
100 
101For type resolution with aliases, you may need to configure TypeScript:
102 
103```json
104// tsconfig.json
105{
106  "compilerOptions": {
107    "paths": {
108      "lodash3": ["node_modules/lodash3"],
109      "lodash4": ["node_modules/lodash4"]
110    }
111  }
112}
113```
114 
115Or use `@types` packages with aliases:
116 
117```json
118{
119  "devDependencies": {
120    "@types/lodash3": "npm:@types/lodash@3",
121    "@types/lodash4": "npm:@types/lodash@4"
122  }
123}
124```
125 
126## Combined with Overrides
127 
128Force all transitive dependencies to use an alias:
129 
130```yaml
131# pnpm-workspace.yaml
132overrides:
133  "underscore": "npm:lodash@^4.17.21"
134```
135 
136This replaces all `underscore` imports (including in dependencies) with lodash.
137 
138## Git and Local Aliases
139 
140Aliases work with any valid pnpm specifier:
141 
142```json
143{
144  "dependencies": {
145    "my-fork": "npm:user/repo#commit",
146    "local-pkg": "file:../local-package"
147  }
148}
149```
150 
151## Best Practices
152 
1531. **Clear naming**: Use descriptive alias names that indicate purpose
154   ```json
155   "lodash-legacy": "npm:lodash@3"
156   "lodash-modern": "npm:lodash@4"
157   ```
158 
1592. **Document aliases**: Add comments or documentation explaining why aliases exist
160 
1613. **Prefer overrides for global replacement**: If you want to replace a package everywhere, use overrides instead of aliases
162 
1634. **Test thoroughly**: Aliased packages may have subtle differences in behavior
164 
165<!-- 
166Source references:
167- https://pnpm.io/aliases
168-->
169