io — text and binary streams

io.BytesIO, io.StringIO, and text-file seek limits: bytes versus characters, and opaque tell() cookies on text files.

The io module defines the stream types used by open() and the in-memory helpers StringIO and BytesIO. It is a standard-library module. Binary streams deal in bytes. Text streams decode and encode Unicode and, for real files, apply a universal newlines translation.

On a binary stream, seek() uses a byte offset. StringIO is an in-memory text stream whose seek() uses a character offset. For a text file, official documentation says the value returned by tell() is an opaque cookie, not a character index or a raw byte index, and you can only seek to 0 or to a position previously returned by tell(). The file example follows that rule. It does not treat an arbitrary integer as a character position.

Examples were checked against Python 3.13. See the official documentation for the complete API.

Python reference overview →

BytesIO and StringIO

BytesIO holds bytes in memory. read() returns bytes, tell() is a byte position, and seek(3) moves to that byte. StringIO holds text. read() returns str, and with the default whence of 0, seek(pos) moves to a character index. Official StringIO documentation also says that seek with whence 1 or 2 requires pos to be 0, so relative seeks are limited even though random access to a character index from the start is supported.

io.BytesIO, io.StringIO

class io.BytesIO(initial_bytes=b'')
class io.StringIO(initial_value='', newline='\n')
stream.read(size=-1)
stream.tell()
stream.seek(offset, whence=0)

Use BytesIO for in-memory bytes and StringIO for in-memory text. Their seek units differ: bytes versus characters.

ParameterDescription
initial_bytes / initial_valueOptional starting contents. BytesIO takes bytes; StringIO takes str.
size, offset, whenceread returns up to size items, or the rest if size is negative or omitted. seek uses a byte offset on BytesIO and a character offset on StringIO when whence is 0.

Returns: read returns bytes on BytesIO and str on StringIO. tell and seek return the new position in the same units.

  • In the StringIO example, "hé" is two characters. tell() is 2, and seek(1) resumes at "é". That character indexing is a StringIO behavior, not the rule for a text file on disk.
python
import io

buf = io.BytesIO(b"abcdef")
print(buf.read(2), buf.tell())
buf.seek(3)
print(buf.read())
text = io.StringIO("héllo")
print(text.read(2), text.tell())
text.seek(1)
print(text.read())

Expected output

b'ab' 2
b'def'
hé 2
éllo

Official documentation →

Seeking a text file

open(path, "w", encoding="utf-8") and open(path, "r", encoding="utf-8") create text streams backed by a file. After reading two characters of "héllo", tell() returns 3 on this host because é is two UTF-8 bytes. Official documentation requires that a later seek use 0 or that cookie, not an invented character index. The example writes and reads only inside a temporary directory.

open, TextIOBase.tell, TextIOBase.seek

open(file, mode='r', encoding=None)
stream.read(size=-1)
stream.tell()
stream.seek(cookie, whence=0)

On a text file, store tell() and seek back to that cookie or to 0. Do not treat the cookie as a character index.

ParameterDescription
file, mode, encodingThe example uses a path inside TemporaryDirectory, writes UTF-8 text, then reopens the file for reading.
cookieAn opaque value returned by tell(), or 0. Official documentation does not support seeking to an arbitrary position in a text file.

Returns: read returns str. tell returns an opaque position. seek returns the new position.

Raises

  • OSError / io.UnsupportedOperation — A stream may raise if it does not support random access, or if a seek is not supported. The example only seeks to 0 and to a previous tell() result.
  • The printed cookie 3 is a measured tell() value after reading "hé" from a UTF-8 file on this host. It is not a portable character index, and this page does not assert what seek(1) would mean on a text file.
python
import os
import tempfile

with tempfile.TemporaryDirectory(prefix="io-ref-") as base:
    path = os.path.join(base, "note.txt")
    with open(path, "w", encoding="utf-8") as file:
        file.write("héllo\nworld")
    with open(path, "r", encoding="utf-8") as file:
        print(file.read(2))
        pos = file.tell()
        print(pos)
        print(file.read())
        file.seek(pos)
        print(file.read())
        file.seek(0)
        print(file.read())

Expected output

hé
3
llo
world
llo
world
héllo
world

Official documentation →