> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK: app file manager

> List, read, write, move and delete the files of an application with client.apps.files. Content travels as base64, so binary files round-trip byte for byte.

The file manager lives on `client.apps.files`. Every method takes the app id first, then a path inside the app. Paths are at most **256 characters**.

Examples use the `client` from [Creating the client](/en/sdks/py/client#creating-the-client). `app_id` is the id of one of your apps: [`client.account.me()`](/en/sdks/py/client#account) lists them.

## Listing a directory

`files.list(app_id, path=None)` lists a directory (the app root when `path` is omitted). Unlike other optional modifiers, `path` can be passed by position.

```python theme={"system"}
for entry in client.apps.files.list(app_id, "/src"):
    print(entry["type"], entry["name"], entry.get("size"), entry.get("lastModified"))
```

| Field | Type | Description |
| - | - | - |
| `name` | `str` | Entry name |
| `type` | `"file" \| "directory"` | Entry kind |
| `size` | `int`, optional | Size in bytes. Absent on some directory entries |
| `lastModified` | `float \| None`, optional | Unix ms (may carry a fraction); `None` when unreadable |

A directory that does not exist is 404 `FILE_NOT_FOUND`. A path the file manager does not expose is 403 `BLOCKED_PATH`.

## Reading a file

`files.read(app_id, path)` returns the file's content as `bytes`. Files are limited to **10 MB**: a larger one is 413 `FILE_TOO_LARGE`.

```python theme={"system"}
import json

data = client.apps.files.read(app_id, "/config.json")
text = data.decode()

print(json.loads(text))
```

## Writing a file

`files.write(app_id, path, content)` creates or overwrites a file.

* A `str` is sent as plain text.
* `bytes` are sent as base64, so any binary content round-trips.
* Empty content (`''` or `b''`) creates an empty file.

```python theme={"system"}
import json
import urllib.request

# Text
client.apps.files.write(app_id, "/config.json", json.dumps({"debug": False}))

# Binary
with urllib.request.urlopen(image_url) as response:
    image = response.read()
client.apps.files.write(app_id, "/assets/logo.png", image)
```

Content over **10 MB** fails locally with `FILE_TOO_LARGE` (status `0`) before anything is sent. Content over **1 MiB** is sent without a timeout once connected, like an upload. For larger files, use [`apps.commit()`](/en/sdks/py/commit_and_upload).

<Note>
  Writing does not restart the app. Call [`apps.restart()`](/en/sdks/py/managing_application#start-stop-and-restart) to apply the change.
</Note>

## Moving or renaming a file

```python theme={"system"}
client.apps.files.move(app_id, "/config.json", "/config.old.json")
```

## Deleting a file

```python theme={"system"}
client.apps.files.delete(app_id, "/config.old.json")
```

## Errors

| Status | Code | When |
| - | - | - |
| 0 | `FILE_TOO_LARGE` | `write` content over 10 MB (checked locally) |
| 400 | `INVALID_PATH` | The path fails validation (traversal, invalid characters, too long), or `move` to the same path |
| 400 | `DELETE_FAILED`, `RENAME_FAILED` | The cluster could not delete or rename the file |
| 403 | `BLOCKED_PATH` | The path is not exposed by the file manager |
| 403 | `PERMISSION_DENIED` | Your workspace role cannot touch a restricted file (such as `.env`) |
| 404 | `FILE_NOT_FOUND` | The file or directory does not exist |
| 413 | `FILE_TOO_LARGE` | `read` of a file over 10 MB |
| 429 | `KEEP_CALM` | More than 10 writes in 5 seconds |

See [Errors](/en/sdks/py/errors) for the codes every call can return.

## Next steps

<CardGroup cols={3}>
  <Card title="Environment variables" icon="key" href="/en/sdks/py/environment_variables">
    Read and change the variables of an app.
  </Card>

  <Card title="File manager API reference" icon="code" href="/en/api-reference/endpoint/apps/filemanager/list">
    The REST endpoints behind these methods.
  </Card>

  <Card title="Manage files from the CLI" icon="terminal" href="/en/cli-reference/files">
    The same actions from the terminal.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.