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

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 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 around lines 538-540:

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 (lines 46-48) declare both options as path-resolvable strings:

"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)

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

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

3. Completely independent locations

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 (lines 133-135):

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, specifically the default-setting logic around line 538
• Runtime verification is available via debug logs in 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, 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 (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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}