read1() returns up tosize bytes, making at most one call to the raw stream below the buffer. If bytes are already buffered it returns those without touching the disk at all.
On a regular file it usually returns exactly what you ask for. Its real value is with pipes and sockets, where read(size) would keep waiting until size bytes arrive but read1() returns whatever is ready.
file.read1() is a method of the file objects that the built-in open() returns, so no import is needed. It works on binary files (BufferedReader, BufferedWriter, BufferedRandom).
Syntax
Call it on a file opened in binary mode such as "rb" or "r+b".
python
chunk = f.read1()
chunk = f.read1(size)
Call
What it does
f.read1(6)
Returns at most 6 bytes, possibly fewer.
f.read1()
Returns up to one buffer's worth (8192 bytes by default).
f.read1(6)
At the end of the file: returns b''.
Before Python 3.7, size was required. A text file has no read1(); its binary layer, f.buffer, does.
Method signatures
python
BufferedReader.read1(size=-1, /) # -> bytes
BufferedRandom.read1(size=-1, /) # -> bytes
io.BytesIO.read1(size=-1, /) # -> bytes
# TextIOWrapper and FileIO have no read1()
Parameters
Parameter
Description
size
Optional. The most bytes to return. Omitted or -1 means "one buffer's worth".
Return Value
Return Value
Description
bytes
Between 1 and size bytes while data remains. On regular files smaller than the buffer, this is min(size, bytes left) in practice.
b''
At the end of the file.
Python Examples
Each example works inside a temporary folder that is deleted at the end, so nothing is left on your disk.
Example 1 — Parse a Length-Prefixed Record
A 4-byte tag, a 2-byte length, then the body: read each part with read1().
python
import os
import tempfile
with tempfile.TemporaryDirectory() as folder:
path = os.path.join(folder, "message.rec")
with open(path, "wb") as f:
f.write(b"REC1" + (5).to_bytes(2, "big") + b"hello")
with open(path, "rb") as f:
tag = f.read1(4)
size = int.from_bytes(f.read1(2), "big")
body = f.read1(size)
print(tag, size, body)
print(f.read1(), f.tell())
Output
b'REC1' 5 b'hello'
b'' 11
How It Works
Build the record.(5).to_bytes(2, "big") stores the body length as the two bytes 00 05 after the tag.
Small, exact reads. On this tiny regular file each read1(n) returns exactly n bytes: the tag, the length, then the body.
Length drives the read.int.from_bytes(..., "big") turns b'\x00\x05' back into 5, which sizes the body read.
End of data. All 11 bytes are consumed, so read1() with no size returns b'' and tell() reports 11.
Example 2 — Copy a File with a read1() Loop
Copy bytes into an in-memory buffer in pieces of at most 6 bytes and record each piece size.
python
import io
import os
import tempfile
with tempfile.TemporaryDirectory() as folder:
path = os.path.join(folder, "photo.raw")
with open(path, "wb") as f:
f.write(b"0123456789ABCDE")
copy = io.BytesIO()
sizes = []
with open(path, "rb") as f:
while chunk := f.read1(6):
sizes.append(len(chunk))
copy.write(chunk)
print(sizes)
print(copy.getvalue() == b"0123456789ABCDE")
Output
[6, 6, 3]
True
How It Works
Walrus loop.while chunk := f.read1(6): (Python 3.8+) reads and tests in one line; the loop ends when b'' comes back.
Pieces never exceed 6. The 15-byte file arrives as 6 + 6 + 3 bytes here; on a pipe the pieces could be smaller, and the loop would still work.
In-memory target.io.BytesIO collects the pieces so the copy can be checked without a second file.
Exact copy. Comparing getvalue() with the original bytes prints True.
Example 3 — Check Which File Objects Have read1()
Compare the text wrapper, its binary buffer, a raw file, and an in-memory byte stream.
python
import io
import os
import tempfile
with tempfile.TemporaryDirectory() as folder:
path = os.path.join(folder, "lines.txt")
with open(path, "w", encoding="utf-8") as f:
f.write("alpha\nbeta\n")
with open(path, encoding="utf-8") as text_file:
print(type(text_file).__name__, hasattr(text_file, "read1"))
print(type(text_file.buffer).__name__, hasattr(text_file.buffer, "read1"))
with open(path, "rb", buffering=0) as raw_file:
print(type(raw_file).__name__, hasattr(raw_file, "read1"))
memory = io.BytesIO(b"in-memory bytes")
print(memory.read1(9))
Text layer. A file opened in text mode is a TextIOWrapper, which works with characters and has no read1().
Buffer underneath. Its .buffer attribute is the BufferedReader that does the byte work, and that object has read1().
Raw layer.buffering=0 skips the buffer and returns a FileIO; with no buffer there is nothing for read1() to use.
BytesIO counts too. An in-memory io.BytesIO supports read1(), here returning the first 9 bytes.
Frequently Asked Questions
read(size) keeps reading until it has size bytes or reaches the end. read1(size) makes at most one raw read and returns whatever it gets, which may be fewer bytes.
No. TextIOWrapper has no read1() and raises AttributeError. Open the file with "rb", or use f.buffer.read1() only if you do not also read through the text layer.
No. It returns at most n bytes. On small regular files it usually returns n while data remains, but on pipes and sockets it often returns less, so always loop.
Up to one buffer of data, which is 8192 bytes by default (io.DEFAULT_BUFFER_SIZE), or b"" at the end of the file.
When you want data as soon as it is available, such as streaming from a pipe or socket, or when you are implementing your own buffering on top of a binary stream.