Quick Reference

This section lists the bitstring module’s classes together with all their methods and attributes. The next section goes into full detail with examples.


Bits is the most basic class. It is immutable, so once created its value cannot change. It is a base class for all the other classes in the bitstring module.


  • all – Check if all specified bits are set to 1 or 0.

  • any – Check if any of specified bits are set to 1 or 0.

  • copy – Return a copy of the bitstring.

  • count – Count the number of bits set to 1 or 0.

  • cut – Create generator of constant sized chunks.

  • endswith – Return whether the bitstring ends with a sub-bitstring.

  • find – Find a sub-bitstring in the current bitstring.

  • findall – Find all occurrences of a sub-bitstring in the current bitstring.

  • join – Join bitstrings together using current bitstring.

  • pp – Pretty print the bitstring.

  • rfind – Seek backwards to find a sub-bitstring.

  • split – Create generator of chunks split by a delimiter.

  • startswith – Return whether the bitstring starts with a sub-bitstring.

  • tobytes – Return bitstring as bytes, padding if needed.

  • tofile – Write bitstring to file, padding if needed.

  • unpack – Interpret bits using format string.

Special methods

Also available are the operators [], ==, !=, +, *, ~, <<, >>, &, | and ^.


  • bin / b – The bitstring as a binary string.

  • bool – For single bit bitstrings, interpret as True or False.

  • bytes – The bitstring as a bytes object.

  • float / floatbe / f – Interpret as a big-endian floating point number.

  • floatle – Interpret as a little-endian floating point number.

  • floatne – Interpret as a native-endian floating point number.

  • bfloat / bfloatbe – Interpret as a big-endian bfloat floating point number.

  • bfloatle – Interpret as a little-endian bfloat floating point number.

  • bfloatne – Interpret as a native-endian bfloat floating point number.

  • hex / h – The bitstring as a hexadecimal string.

  • int / i – Interpret as a two’s complement signed integer.

  • intbe – Interpret as a big-endian signed integer.

  • intle – Interpret as a little-endian signed integer.

  • intne – Interpret as a native-endian signed integer.

  • len – Length of the bitstring in bits.

  • oct / o – The bitstring as an octal string.

  • se – Interpret as a signed exponential-Golomb code.

  • ue – Interpret as an unsigned exponential-Golomb code.

  • sie – Interpret as a signed interleaved exponential-Golomb code.

  • uie – Interpret as an unsigned interleaved exponential-Golomb code.

  • uint / u – Interpret as a two’s complement unsigned integer.

  • uintbe – Interpret as a big-endian unsigned integer.

  • uintle – Interpret as a little-endian unsigned integer.

  • uintne – Interpret as a native-endian unsigned integer.



This class adds mutating methods to Bits.

Additional methods

  • append – Append a bitstring.

  • byteswap – Change byte endianness in-place.

  • clear – Remove all bits from the bitstring.

  • insert – Insert a bitstring.

  • invert – Flip bit(s) between one and zero.

  • overwrite – Overwrite a section with a new bitstring.

  • prepend – Prepend a bitstring.

  • replace – Replace occurrences of one bitstring with another.

  • reverse – Reverse bits in-place.

  • rol – Rotate bits to the left.

  • ror – Rotate bits to the right.

  • set – Set bit(s) to 1 or 0.

Additional special methods

Mutating operators are available: [], <<=, >>=, *=, &=, |= and ^=.


The same as Bits, except that they are all (with the exception of len) writable as well as readable.



This class adds a bit position and methods to read and navigate in the bitstream.

Additional methods

  • bytealign – Align to next byte boundary.

  • peek – Peek at and interpret next bits as a single item.

  • peeklist – Peek at and interpret next bits as a list of items.

  • read – Read and interpret next bits as a single item.

  • readlist – Read and interpret next bits as a list of items.

  • readto – Read up to and including next occurrence of a bitstring.

Additional properties

  • bytepos – The current byte position in the bitstring.

  • pos – The current bit position in the bitstring.


BitStream(BitArray, ConstBitStream)

This class contains all of the ‘stream’ elements of ConstBitStream and adds all of the mutating methods of BitArray. It is the most general of the four classes, but it is usually best to choose the simplest class for your use case.

Module level


  • pack – Create a new BitStream according to a format string and values.


  • Error – Base class for module exceptions.

  • ReadError – Reading or peeking past the end of a bitstring.

  • InterpretError – Inappropriate interpretation of binary data.

  • ByteAlignError – Whole-byte position or length needed.

  • CreationError – Inappropriate argument during bitstring creation.

Module variables

  • bytealigned – Determines whether a number of methods default to working only on byte boundaries.

  • lsb0 – If True, index bits with the least significant bit (the final bit) as bit zero.