# How `--user-data-dir` and `--extensions-dir` Work Together in code-server

> Understand how code-server's --user-data-dir and --extensions-dir interact. Learn to manage extensions independently and customize their storage location.

- Repository: [Coder/code-server](https://github.com/coder/code-server)
- Tags: internals
- Published: 2026-03-01

---

**When you omit `--extensions-dir`, code-server automatically creates an extensions folder inside your `--user-data-dir` path, but you can override this to store extensions independently on any filesystem location.**

[Coder/code-server](https://github.com/coder/code-server) is an open-source platform that runs VS Code in the browser, allowing developers to code remotely. Understanding the relationship between the **`--user-data-dir`** and **`--extensions-dir`** flags is essential for managing storage locations, optimizing performance with fast disks, and configuring multi-instance deployments.

## Default Directory Hierarchy

By default, **`--user-data-dir`** serves as the root directory for all per-user state, including settings, cached data, and the extensions directory. If you launch code-server without specifying **`--extensions-dir`**, the CLI automatically defaults the extensions path to a subdirectory named `extensions` inside the user data directory.

This logic is implemented in [`src/node/cli.ts`](https://github.com/coder/code-server/blob/main/src/node/cli.ts) around lines 538-540:

```typescript
if (!args["extensions-dir"]) {
  args["extensions-dir"] = path.join(args["user-data-dir"], "extensions")
}

```

When neither flag is provided, `--user-data-dir` defaults to `paths.data` (typically `~/.local/share/code-server` on Linux), meaning extensions would reside at `~/.local/share/code-server/extensions`.

## Overriding the Default Location

When you explicitly provide the **`--extensions-dir`** flag, code-server treats the two directories as independent entities. This override completely decouples the extensions storage from the user data root, allowing you to store extensions on a fast SSD while keeping user data on network storage, or share a single extensions directory across multiple code-server instances.

The CLI argument definitions in [`src/node/cli.ts`](https://github.com/coder/code-server/blob/main/src/node/cli.ts) (lines 46-48) declare both options as path-resolvable strings:

```typescript
"extensions-dir": { type: "string", path: true, description: "Path to the extensions directory." },

```

## Configuration Examples

Here are three common deployment patterns illustrating the relationship between these flags.

**1. Default behavior (extensions nested under user data)**

```bash
code-server --user-data-dir /home/alice/.local/share/my-code-server

```

Extensions install to `/home/alice/.local/share/my-code-server/extensions`.

**2. Override only the extensions directory**

```bash
code-server \
  --user-data-dir /home/alice/.local/share/my-code-server \
  --extensions-dir /mnt/fastssd/vscode-extensions

```

**3. Completely independent locations**

```bash
code-server \
  --user-data-dir /srv/code-server/data \
  --extensions-dir /srv/code-server/exts

```

In all cases, commands like `--install-extension` write to the path specified by `--extensions-dir`.

## Verifying Your Configuration

At startup, code-server logs the resolved directory paths to help verify your configuration. The debug output is generated in [`src/node/main.ts`](https://github.com/coder/code-server/blob/main/src/node/main.ts) (lines 133-135):

```typescript
logger.debug(`Using user-data-dir ${args["user-data-dir"]}`)
logger.debug(`Using extensions-dir ${args["extensions-dir"]}`)

```

Run code-server with `--log debug` to see these values in your startup output.

## Summary

- **`--extensions-dir` defaults to a subdirectory** of `--user-data-dir` when not explicitly set
- **Explicit override decouples the directories**, allowing independent filesystem locations
- **Source logic resides in [`src/node/cli.ts`](https://github.com/coder/code-server/blob/main/src/node/cli.ts)**, specifically the default-setting logic around line 538
- **Runtime verification** is available via debug logs in [`src/node/main.ts`](https://github.com/coder/code-server/blob/main/src/node/main.ts)
- **Use cases** include separating extensions onto fast storage or sharing extensions across instances

## Frequently Asked Questions

### What happens if I specify `--user-data-dir` but omit `--extensions-dir`?

Code-server automatically creates an `extensions` folder inside your user data directory. According to the default-setting logic in [`src/node/cli.ts`](https://github.com/coder/code-server/blob/main/src/node/cli.ts), the CLI joins the user data path with the string `"extensions"` to form the final extensions directory path.

### Can I store my extensions on a different physical drive than my user data?

Yes. By explicitly setting `--extensions-dir` to an absolute path on another mount point (such as `/mnt/fastssd/vscode-extensions`), you completely decouple the storage locations. This is useful for placing extensions on fast SSDs while keeping user configuration files on slower network-attached storage.

### Where does code-server log the resolved directory paths at startup?

The application emits debug-level log statements in [`src/node/main.ts`](https://github.com/coder/code-server/blob/main/src/node/main.ts) (lines 133-135) that display the fully resolved paths for both `--user-data-dir` and `--extensions-dir`. Enable debug logging with the `--log debug` flag to view these messages in your terminal output.

### What is the default value for `--user-data-dir` if I don't specify it?

When omitted, `--user-data-dir` defaults to `paths.data`, which typically resolves to `~/.local/share/code-server` on Linux systems. Consequently, without any flags specified, extensions would install to `~/.local/share/code-server/extensions`.