# userdir

> A simple utility to get the cross-platform user home directory

Latest version **1.1.0** (published 2026-03-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install userdir
pnpm add userdir
yarn add userdir
bun add userdir
```

## Health

**Score 65/100 (B)** — status: stable.

Positive: has types; esm support; no vulnerabilities; has provenance; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2026-03-17 |
| First published | 2023-02-12 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 0 |
| Unpacked size | 19.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 3 |
| Author | saqqdy |
| Maintainers | saqqdy |
| Keywords | userdir, userhome, homedir, home, home-directory, cross-platform, saqqdy |

## Links

- npm: https://www.npmjs.com/package/userdir
- Repository: https://github.com/saqqdy/userdir
- Homepage: https://github.com/saqqdy/userdir#readme
- Issues: https://github.com/saqqdy/userdir/issues
- npm.io page: https://npm.io/package/userdir

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 1.1.0 (latest) — 2026-03-17
- 1.0.0-beta.1 (beta) — 2023-02-26
- 1.0.0-alpha.1 (alpha) — 2023-02-13
- 1.0.0 — 2023-02-27
- 1.0.0-alpha.0 — 2023-02-12

## README

<div style="text-align: center;" align="center">

# userdir

A simple utility to get the cross-platform user home directory

[![NPM version][npm-image]][npm-url]
[![npm download][download-image]][download-url]
[![License][license-image]][license-url]

</div>

<div style="text-align: center; margin-bottom: 20px;" align="center">

### **[Change Log](./CHANGELOG.md)** · **[简体中文](./README_CN.md)**

</div>

## Installing

```bash
# use pnpm
$ pnpm install userdir

# use npm
$ npm install userdir

# use yarn
$ yarn add userdir
```

## Requirements

- Node.js >= 18

## Usage

### Basic Usage

```js
import userdir from 'userdir'

userdir() // /Users/username
```

### With Options

```js
import { userdir, userdirAsync, clearCache } from 'userdir'

// With path validation
userdir({ validate: true }) // Returns null if path doesn't exist

// Without cache
userdir({ cache: false })

// Async version
await userdirAsync()

// Clear cache
clearCache()
```

### Options

```typescript
interface UserdirOptions {
  /** Whether to use cache (default: true) */
  cache?: boolean
  /** Custom environment variables (for testing) */
  env?: typeof process.env
  /** Validate if directory exists (default: false) */
  validate?: boolean
}
```

## API

### `userdir(options?)`

Get the user home directory synchronously.

- **Returns**: `string | null` - User home directory path, or null if not found

### `userdirAsync(options?)`

Get the user home directory asynchronously.

- **Returns**: `Promise<string | null>`

### `clearCache()`

Clear the internal cache.

### Default Export

The default export uses `os.homedir()` when available, falls back to `userdir()`.

## Migration from v1.0 to v1.1

### Node.js Version

v1.1 requires Node.js >= 18. If you need to support older versions, stay on v1.0.

### Import Changes

The default export behavior remains the same. Named exports are now available:

```js
// v1.0
import userdir from 'userdir'

// v1.1 - Same as before
import userdir from 'userdir'

// v1.1 - New named exports
import { userdir, userdirAsync, clearCache } from 'userdir'
```

### New Features

```js
// Path validation (returns null if path doesn't exist)
userdir({ validate: true })

// Disable cache
userdir({ cache: false })

// Async API
await userdirAsync()

// Clear cache manually
clearCache()
```

### Removed Dependencies

v1.1 no longer depends on `core-js` or `js-cool`. If your project relied on these being installed transitively, install them directly.

### Build Output

| v1.0 | v1.1 |
|------|------|
| `dist/index.mjs` | `dist/index.js` |
| `dist/index.cjs` | `dist/index.cjs` |

## Support & Issues

Please open an issue [here](https://github.com/saqqdy/userdir/issues).

## License

[MIT](LICENSE)

[npm-image]: https://img.shields.io/npm/v/userdir.svg?style=flat-square
[npm-url]: https://npmjs.org/package/userdir
[download-image]: https://img.shields.io/npm/dm/userdir.svg?style=flat-square
[download-url]: https://npmjs.org/package/userdir
[license-image]: https://img.shields.io/badge/License-MIT-blue.svg
[license-url]: LICENSE

---
_Source: https://npm.io/package/userdir · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._