---
title: Filesystem
description: Python SDK - Filesystem API reference
---
Read and write files inside a running sandbox. See [Filesystem](/sandboxes/filesystem) for usage examples.
## SandboxFsOps
#### fs.read()
```python
async def read(path: str) -> bytes
```
```python
raw = await sb.fs.read("/app/data.bin")
print(len(raw))
```
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.
#### fs.read_text()
```python
async def read_text(path: str) -> str
```
```python
config = await sb.fs.read_text("/app/config.json")
```
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.
#### fs.read_stream()
```python
async def read_stream(path: str) -> FsReadStream
```
```python
stream = await sb.fs.read_stream("/app/large.log")
async for chunk in stream:
process(chunk)
```
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.
#### fs.write()
```python
async def write(path: str, data: bytes) -> None
```
```python
await sb.fs.write("/app/hello.txt", b"hi\n")
```
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.
#### fs.write_stream()
```python
async def write_stream(path: str) -> FsWriteSink
```
```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")
```
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.
#### fs.list()
```python
async def list(path: str) -> list[FsEntry]
```
```python
for entry in await sb.fs.list("/app"):
print(entry.kind, entry.path)
```
List the entries in a directory.
Parameters
pathstr
Absolute directory path inside the guest.
Returns
#### fs.mkdir()
```python
async def mkdir(path: str) -> None
```
```python
await sb.fs.mkdir("/app/data/cache")
```
Create a directory, including any missing parent directories.
Parameters
pathstr
Absolute directory path inside the guest.
#### fs.stat()
```python
async def stat(path: str) -> FsMetadata
```
```python
meta = await sb.fs.stat("/app/config.json")
print(meta.kind, meta.size, meta.readonly)
```
Get detailed metadata for a file or directory.
Parameters
pathstr
Absolute path inside the guest.
Returns
#### fs.exists()
```python
async def exists(path: str) -> bool
```
```python
if not await sb.fs.exists("/app/config.json"):
await sb.fs.write("/app/config.json", b"{}")
```
Check whether a path exists inside the sandbox.
Parameters
pathstr
Absolute path inside the guest.
Returns
bool
True if the path exists.
#### fs.remove_dir()
```python
async def remove_dir(path: str) -> None
```
```python
await sb.fs.remove_dir("/app/data/cache")
```
Remove a directory and its contents recursively.
Parameters
pathstr
Absolute directory path inside the guest.
#### fs.copy()
```python
async def copy(src: str, dst: str) -> None
```
```python
await sb.fs.copy("/app/config.json", "/app/config.bak.json")
```
Copy a file within the sandbox.
Parameters
srcstr
Source path inside the guest.
dststr
Destination path inside the guest.
#### fs.rename()
```python
async def rename(src: str, dst: str) -> None
```
```python
await sb.fs.rename("/app/tmp.txt", "/app/final.txt")
```
Rename or move a file or directory within the sandbox.
Parameters
srcstr
Current path inside the guest.
dststr
New path inside the guest.
#### fs.remove()
```python
async def remove(path: str) -> None
```
```python
await sb.fs.remove("/app/config.bak.json")
```
Remove a file. Use [`remove_dir()`](#fs-remove_dir) for directories.
Parameters
pathstr
Absolute file path inside the guest.
#### fs.copy_from_host()
```python
async def copy_from_host(host_path: str, guest_path: str) -> None
```
```python
await sb.fs.copy_from_host("./local/seed.csv", "/app/seed.csv")
```
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.
#### fs.copy_to_host()
```python
async def copy_to_host(guest_path: str, host_path: str) -> None
```
```python
await sb.fs.copy_to_host("/app/report.pdf", "./report.pdf")
```
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.
## FsReadStream
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.
#### stream.__aiter__()
```python
__aiter__()
```
Async iterator. Use `async for chunk in stream:`.
Returns
`bytes`
#### stream.__anext__()
```python
__anext__()
```
Async iterator. Use `async for chunk in stream:`.
Returns
`bytes`
#### stream.collect()
```python
collect()
```
*(async)* Collect all remaining data into a single `bytes` object
Returns
`bytes`
## FsWriteSink
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.
#### sink.write()
```python
write(data)
```
*(async)* Write a chunk of `bytes` to the file
#### sink.close()
```python
close()
```
*(async)* Send EOF and finalize the file
#### sink.__aenter__()
```python
__aenter__()
```
*(async)* Use with `async with` for automatic close on exit
Returns
`FsWriteSink`
#### sink.__aexit__()
```python
__aexit__()
```
*(async)* Use with `async with` for automatic close on exit
Returns
`FsWriteSink`
## Types
### FsEntry
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 | [`FsEntryKind`](#fsentrykind) | Entry type |
| size | `int` | File size in bytes |
| mode | `int` | Unix permission bits |
| modified | `float \| None` | Last-modified time, milliseconds since the Unix epoch |
### FsEntryKind
Describes FsEntry.kind ยท FsMetadata.kind
Filesystem entry type returned by [`FsEntry.kind`](#fsentry) and [`FsMetadata.kind`](#fsmetadata).
| Member | Value | Description |
|--------|-------|-------------|
| `FsEntryKind.FILE` | `"file"` | Regular file |
| `FsEntryKind.DIRECTORY` | `"directory"` | Directory |
| `FsEntryKind.SYMLINK` | `"symlink"` | Symbolic link |
| `FsEntryKind.OTHER` | `"other"` | Other entry type |
```python
from microsandbox import FsEntryKind
files = [entry for entry in await sb.fs.list("/app") if entry.kind is FsEntryKind.FILE]
```
### FsMetadata
Returned by stat()
Detailed file metadata, returned by [`stat()`](#fs-stat).
| Property | Type | Description |
|----------|------|-------------|
| kind | [`FsEntryKind`](#fsentrykind) | Entry type |
| 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 |