> ## Documentation Index
> Fetch the complete documentation index at: https://e2b.manicule.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For every page in one file, fetch https://e2b.manicule.dev/llms-full.txt (large).
> To search and read these docs as tools, connect the MCP server at https://e2b.manicule.dev/api/mcp.
> Every agent surface: https://e2b.manicule.dev/.well-known/llms-manifest.json

# Attach custom metadata to files (/docs/filesystem/metadata)

<!-- agent-signals: reading_time_min: 2 · est_tokens: 751 · updated: 2026-07-30 -->
Related: [Download data from sandbox](/docs/filesystem/download.md), [Get information about a file or directory](/docs/filesystem/info.md), [Read & write files](/docs/filesystem/read-write.md), [Upload data to sandbox](/docs/filesystem/upload.md), [Watch sandbox directory for changes](/docs/filesystem/watch.md)

> Attach custom key-value metadata to files when writing them to the sandbox and read it back with file info methods.

You can attach custom key-value metadata to files when writing them to the sandbox using the `metadata` option.
The metadata is persisted with the file and returned by `files.getInfo()` / `files.get_info()`, `files.list()`, and `files.rename()`.

## Prerequisites

Custom file metadata requires templates with envd version `v0.6.2` or above. If you are using a custom template created before envd `v0.6.2`, you need to rebuild it.

You can check the template envd version using the `e2b template list` command or by viewing the templates list on the dashboard.

## Writing a file with metadata

<CodeGroup>
```js title="JavaScript & TypeScript"
import { Sandbox } from 'e2b'

const sandbox = await Sandbox.create()

const info = await sandbox.files.write('report.txt', 'hello', {
  metadata: { author: 'alice', purpose: 'demo' },
})
console.log(info.metadata) // { author: 'alice', purpose: 'demo' }
```

```python title="Python"
from e2b import Sandbox

sandbox = Sandbox.create()

info = sandbox.files.write("report.txt", "hello", metadata={"author": "alice", "purpose": "demo"})
print(info.metadata)  # {"author": "alice", "purpose": "demo"}
```
</CodeGroup>

## Writing multiple files with metadata

When writing multiple files, the same metadata is applied to every file in the upload.

<CodeGroup>
```js title="JavaScript & TypeScript"
import { Sandbox } from 'e2b'

const sandbox = await Sandbox.create()

await sandbox.files.writeFiles(
  [
    { path: 'a.txt', data: 'A' },
    { path: 'b.txt', data: 'B' },
  ],
  { metadata: { source: 'import' } }
)
```

```python title="Python"
from e2b import Sandbox

sandbox = Sandbox.create()

sandbox.files.write_files(
    [
        { "path": "a.txt", "data": "A" },
        { "path": "b.txt", "data": "B" },
    ],
    metadata={"source": "import"},
)
```
</CodeGroup>

## Reading metadata back

<CodeGroup>
```js title="JavaScript & TypeScript"
import { Sandbox } from 'e2b'

const sandbox = await Sandbox.create()

await sandbox.files.write('report.txt', 'hello', {
  metadata: { author: 'alice' },
})

const info = await sandbox.files.getInfo('report.txt')
console.log(info.metadata) // { author: 'alice' }
```

```python title="Python"
from e2b import Sandbox

sandbox = Sandbox.create()

sandbox.files.write("report.txt", "hello", metadata={"author": "alice"})

info = sandbox.files.get_info("report.txt")
print(info.metadata)  # {"author": "alice"}
```
</CodeGroup>

## Limitations

* Metadata keys and values must be printable US-ASCII characters.
* Keys are lowercased by the sandbox, so they may differ in case when read back.
* Overwriting a file replaces its metadata — metadata from the previous write is not preserved.
* Metadata is stored as `user.e2b.*` extended attributes on the file inside the sandbox, so you can also read or set it from within the sandbox using standard tools like `getfattr` and `setfattr`.