# Custom metadata
<subtitle>Appends custom key-value pair metadata to the file and obtains it when reading. </subtitle>

You can use the `metadata` option to append custom key-value pair metadata when writing files to the sandbox. Metadata is persisted with the file and returned by `files.get_info()`, `files.list()`, and `files.rename()`.

## Preconditions

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

You can check the envd version of a template using the `ucloud-sandbox-cli template list` command.

## Write files with metadata

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create()

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

## Write multiple files with metadata

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

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create()

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

## Read metadata

```python
from ucloud_sandbox 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"}
```

## limit

- Metadata keys and values ​​must be printable US-ASCII characters.
- Keys are converted to lowercase by the sandbox, so the case may be different when reading than when writing.
- Overwriting a file replaces its metadata - previously written metadata is not preserved.
- Metadata is stored as `user.e2b.*` extended properties on files inside the sandbox, so you can also read or set it inside the sandbox using standard tools such as `getfattr` and `setfattr`.