---
title: Filesystem
description: Python SDK - Filesystem API reference
---
Read, write, and manage files inside a running sandbox. Operations go through the same host-guest channel as command execution: no SSH, no network. See [Filesystem](/sandboxes/filesystem) for usage examples. For bulk file movement, prefer a [volume](/sandboxes/volumes).
Typical flow
```python
from microsandbox import Sandbox
async with await Sandbox.create("api", image="python") as sb:
fs = sb.fs # 1. grab the handle
await fs.mkdir("/app") # 2. set up
await fs.write("/app/config.json", b'{"ok": true}')
data = await fs.read_text("/app/config.json") # 3. read it back
print(data)
```
The handle is reached through the `sb.fs` property on a running [`Sandbox`](/sdk/python/sandbox). All methods are coroutines, so `await` each call.
## Methods
---
#### fs.read()
instanceasync
```python
async def read(path: str) -> bytes
```
Read the entire contents of a file as raw bytes.
Parameters
pathstr
Absolute path inside the guest, e.g. "/app/config.json".
Returns
bytes
File contents as raw bytes.
```python
raw = await sb.fs.read("/app/data.bin")
print(len(raw))
```
---
#### fs.read_text()
instanceasync
```python
async def read_text(path: str) -> str
```
Read the entire contents of a file and decode it as UTF-8.
Parameters
pathstr
Absolute path inside the guest.
Returns
str
File contents decoded as UTF-8.
```python
config = await sb.fs.read_text("/app/config.json")
```
---
#### fs.read_stream()
instanceasync
```python
async def read_stream(path: str) -> FsReadStream
```
Open a streaming reader for a file. Use this for files too large to hold in memory. The returned [`FsReadStream`](#fsreadstream) is an async iterator that yields chunks of bytes, or call its `collect()` to gather everything into one `bytes`.
Parameters
pathstr
Absolute path inside the guest.
Returns
Async iterator yielding chunks of file data.
```python
stream = await sb.fs.read_stream("/app/large.log")
async for chunk in stream:
process(chunk)
```
---
#### fs.write()
instanceasync
```python
async def write(path: str, data: bytes) -> None
```
Write content to a file, creating it if it doesn't exist and overwriting it if it does.
Parameters
pathstr
Absolute path inside the guest.
```python
await sb.fs.write("/app/hello.txt", b"hi\n")
```
---
#### fs.write_stream()
instanceasync
```python
async def write_stream(path: str) -> FsWriteSink
```
Open a streaming writer for a file. Use this for files too large to hold in memory. The returned [`FsWriteSink`](#fswritesink) supports the async context manager protocol, so `async with` closes and finalizes the file automatically.
Parameters
pathstr
Absolute path inside the guest.
Returns
Async writer that accepts chunks of bytes.
```python
async with await sb.fs.write_stream("/app/out.bin") as sink:
await sink.write(b"chunk one")
await sink.write(b"chunk two")
```
---
#### fs.list()
instanceasync
```python
async def list(path: str) -> list[FsEntry]
```
List the entries in a directory.
Parameters
pathstr
Absolute directory path inside the guest.
Returns
```python
for entry in await sb.fs.list("/app"):
print(entry.kind, entry.path)
```
---
#### fs.mkdir()
instanceasync
```python
async def mkdir(path: str) -> None
```
Create a directory, including any missing parent directories.
Parameters
pathstr
Absolute directory path inside the guest.
```python
await sb.fs.mkdir("/app/data/cache")
```
---
#### fs.stat()
instanceasync
```python
async def stat(path: str) -> FsMetadata
```
Get detailed metadata for a file or directory.
Parameters
pathstr
Absolute path inside the guest.
Returns
```python
meta = await sb.fs.stat("/app/config.json")
print(meta.kind, meta.size, meta.readonly)
```
---
#### fs.exists()
instanceasync
```python
async def exists(path: str) -> bool
```
Check whether a path exists inside the sandbox.
Parameters
pathstr
Absolute path inside the guest.
Returns
bool
True if the path exists.
```python
if not await sb.fs.exists("/app/config.json"):
await sb.fs.write("/app/config.json", b"{}")
```
---
#### fs.remove_dir()
instanceasync
```python
async def remove_dir(path: str) -> None
```
Remove a directory and its contents recursively.
Parameters
pathstr
Absolute directory path inside the guest.
```python
await sb.fs.remove_dir("/app/data/cache")
```
---
#### fs.copy()
instanceasync
```python
async def copy(src: str, dst: str) -> None
```
Copy a file within the sandbox.
Parameters
srcstr
Source path inside the guest.
dststr
Destination path inside the guest.
```python
await sb.fs.copy("/app/config.json", "/app/config.bak.json")
```
---
#### fs.rename()
instanceasync
```python
async def rename(src: str, dst: str) -> None
```
Rename or move a file or directory within the sandbox.
Parameters
srcstr
Current path inside the guest.
dststr
New path inside the guest.
```python
await sb.fs.rename("/app/tmp.txt", "/app/final.txt")
```
---
#### fs.remove()
instanceasync
```python
async def remove(path: str) -> None
```
Remove a file. Use [`remove_dir()`](#fs-remove_dir) for directories.
Parameters
pathstr
Absolute file path inside the guest.
```python
await sb.fs.remove("/app/config.bak.json")
```
---
#### fs.copy_from_host()
instanceasync
```python
async def copy_from_host(host_path: str, guest_path: str) -> None
```
Copy a file from the host machine into the sandbox. For transferring many files, consider a [bind-mounted volume](/sandboxes/volumes) instead.
Parameters
host_pathstr
Path on the host filesystem.
guest_pathstr
Destination path inside the sandbox.
```python
await sb.fs.copy_from_host("./local/seed.csv", "/app/seed.csv")
```
---
#### fs.copy_to_host()
instanceasync
```python
async def copy_to_host(guest_path: str, host_path: str) -> None
```
Copy a file from the sandbox out to the host machine.
Parameters
guest_pathstr
Path inside the sandbox.
host_pathstr
Destination path on the host.
```python
await sb.fs.copy_to_host("/app/report.pdf", "./report.pdf")
```
---
## Types
### FsEntry
class
Returned by list()
Metadata for a single directory entry, returned by [`list()`](#fs-list).
| Property | Type | Description |
|----------|------|-------------|
| path | `str` | Full path of the entry |
| kind | `str` | Entry type: `"file"`, `"directory"`, `"symlink"`, or `"other"` (see [`FsEntryKind`](#fsentrykind)) |
| size | `int` | File size in bytes |
| mode | `int` | Unix permission bits |
| modified | `float \| None` | Last-modified time, milliseconds since the Unix epoch |
### FsEntryKind
enum
Describes FsEntry.kind ยท FsMetadata.kind
String enum ([`StrEnum`](https://docs.python.org/3/library/enum.html#enum.StrEnum)) of filesystem entry types. The `kind` fields on [`FsEntry`](#fsentry) and [`FsMetadata`](#fsmetadata) carry these string values.
| Value | Description |
|-------|-------------|
| `"file"` | Regular file |
| `"directory"` | Directory |
| `"symlink"` | Symbolic link |
| `"other"` | Other entry type |
### FsMetadata
class
Returned by stat()
Detailed file metadata, returned by [`stat()`](#fs-stat).
| Property | Type | Description |
|----------|------|-------------|
| kind | `str` | Entry type: `"file"`, `"directory"`, `"symlink"`, or `"other"` (see [`FsEntryKind`](#fsentrykind)) |
| size | `int` | File size in bytes |
| mode | `int` | Unix permission bits |
| readonly | `bool` | Whether the file is read-only |
| modified | `float \| None` | Last-modified time, milliseconds since the Unix epoch |
| created | `float \| None` | Creation time, milliseconds since the Unix epoch |
### FsReadStream
class
Returned by read_stream()
Async stream for reading a file in chunks. Obtained via [`read_stream()`](#fs-read_stream). Iterate it with `async for chunk in stream:`, or call `collect()` to gather everything at once.
| Method / Protocol | Returns | Description |
|-------------------|---------|-------------|
| `__aiter__` / `__anext__` | `bytes` | Async iterator. Use `async for chunk in stream:`. |
| collect() | `bytes` | *(async)* Collect all remaining data into a single `bytes` object |
### FsWriteSink
class
Returned by write_stream()
Async writer for streaming data into a file. Obtained via [`write_stream()`](#fs-write_stream). Supports the async context manager protocol, so `async with` closes the sink on exit.
| Method / Protocol | Returns | Description |
|-------------------|---------|-------------|
| write(data) | `None` | *(async)* Write a chunk of `bytes` to the file |
| close() | `None` | *(async)* Send EOF and finalize the file |
| `__aenter__` / `__aexit__` | `FsWriteSink` | *(async)* Use with `async with` for automatic close on exit |