CLAUDE_CODE_ATTACHMENTS_BY_PATH

Updated October 14, 2026 by Alex Sorokoletov

CLAUDE_CODE_ATTACHMENTS_BY_PATH is a Claude Code environment variable: When set, the attachment handler takes the by-path route instead of an upload mode, so attachments are referenced by their file path rather than having their contents uploaded. Added in v2.1.300 and still present in v2.1.300. It is not in the official reference.

Status	Present in v2.1.300
Added	Added in v2.1.300
Category	Other
Official docs	Not listed

How to set it

For one session, export it in the shell that starts Claude Code:

export CLAUDE_CODE_ATTACHMENTS_BY_PATH=<value>
claude

To apply it to every session, add it to the env object of a settings file:

// ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_ATTACHMENTS_BY_PATH": "<value>"
  }
}

Release notes that mention it

claude-code-env-vars-v2-1-300

Related variables

CLAUDE_CODE_ARTIFACT_PATH_PIN
CLAUDE_CODE_MANAGED_SETTINGS_PATH
CLAUDE_CODE_POLICY_HELPER_PS1_PATH
CLAUDE_PTY_HOST_NO_STABLE_PATH
CLAUDE_RUNNER_CHECKOUT_PATH
ANTHROPIC_BETAS: Comma-separated beta feature headers.
ANTHROPIC_CUSTOM_HEADERS: Custom HTTP headers (newline-separated Key: Value).
ANTHROPIC_FEDERATION_RULE_ID

Frequently asked questions

What does CLAUDE_CODE_ATTACHMENTS_BY_PATH do?

When set, the attachment handler takes the by-path route instead of an upload mode, so attachments are referenced by their file path rather than having their contents uploaded.

Which Claude Code version has CLAUDE_CODE_ATTACHMENTS_BY_PATH?

Added in v2.1.300 and still present in v2.1.300.

How do I set CLAUDE_CODE_ATTACHMENTS_BY_PATH?

Export it before starting Claude Code (export CLAUDE_CODE_ATTACHMENTS_BY_PATH=value), or add it to the "env" object in ~/.claude/settings.json to apply it to every session.

All variables, searchable: Claude Code environment variables.