Install & Compatibility
Where this runs
tested against v0.7.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.148s · 41.5MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.5s · import 0.137s · 44MB
42MB installed
● package 42MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
thriftpy2
✓ import thriftpy2
Main library import for dynamic IDL loading and core functionalities.
make_server
✓ from thriftpy2.rpc import make_server
Used to create synchronous Thrift RPC servers.
make_aio_client
✓ from thriftpy2.rpc import make_aio_client
Used to create asynchronous Thrift RPC clients with asyncio.
thriftpy
✓ import thriftpy2 as thriftpy
✗ import thriftpy
The original 'thriftpy' library is deprecated. For compatibility, migrate to 'thriftpy2' and import it with an alias if needed.
This quickstart demonstrates how to dynamically load a Thrift IDL file and instantiate an asynchronous client using `thriftpy2.rpc.make_aio_client`. It creates a temporary `pingpong.thrift` file, loads it, and attempts to connect to a local server. Note that for a successful RPC call, a ThriftPy2 server must be running at the specified address and port.
import asyncio
import thriftpy2
from thriftpy2.rpc import make_aio_client
import os
# Define a simple Thrift service IDL in a temporary file
THRIFT_FILE_PATH = "pingpong.thrift"
with open(THRIFT_FILE_PATH, "w") as f:
f.write("service PingPong {\n string ping(),\n}")
# Load the thrift file dynamically
pingpong_thrift = thriftpy2.load(THRIFT_FILE_PATH, module_name="pingpong_thrift")
async def main():
print("Attempting to create ThriftPy2 async client...")
client = None
try:
# For this quickstart, we'll demonstrate client instantiation and a call pattern.
# Note: This client will attempt to connect to '127.0.0.1:6000'.
# A running ThriftPy2 server on this address would be required for a successful RPC call.
# This example focuses on demonstrating the client API, not a full RPC pair.
client = await make_aio_client(
pingpong_thrift.PingPong,
'127.0.0.1',
6000,
timeout=1000 # Milliseconds for connection/read timeout
)
print("Client created. Attempting to call ping()... (This will likely fail without a running server)")
# Example of calling a service method
# result = await client.ping()
# print(f"Ping result: {result}")
except Exception as e:
print(f"Error setting up client (expected if no server is running at 127.0.0.1:6000): {e}")
finally:
if client:
client.close()
# Clean up the dummy thrift file
if os.path.exists(THRIFT_FILE_PATH):
os.remove(THRIFT_FILE_PATH)
if __name__ == '__main__':
asyncio.run(main())
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'thriftpy'
The user is trying to import the old `thriftpy` library, or made a typo when intending to use `thriftpy2`.
fixInstall `thriftpy2` (`pip install thriftpy2`) and update all imports from `thriftpy` to `thriftpy2`.
thriftpy2.parser.exc.ThriftParserError: Line X: Expected identifier.
There is a syntax error or a semantic issue in the Thrift IDL (.thrift) file that `thriftpy2` is trying to load. The specific message 'Expected identifier' indicates a name is missing or incorrectly placed.
fixReview and correct the syntax of the Thrift IDL file at the specified line number. Ensure all identifiers (like struct names, field names, method names) are correctly defined and that there are no missing semicolons or incorrect keywords.
TProtocolException: Bad version in readMessageBegin
The client and server are using incompatible Thrift protocol versions or transport layers. This often occurs when `thriftpy2` communicates with a service implemented in a different language or Thrift library that uses a different default protocol (e.g., TBinaryProtocol vs TCompactProtocol) or an incompatible transport.
fixEnsure both the client and server are configured to use the exact same Thrift protocol factory (e.g., `TBinaryProtocol.TBinaryProtocolFactory()`, `TCompactProtocol.TCompactProtocolFactory()`) and transport factory (e.g., `TSocket.TSocketFactory()`, `TBufferedTransport.TBufferedTransportFactory()`).
AttributeError: 'Client' object has no attribute 'yourMethodName'
The Thrift client code is attempting to call a method that is not defined in the Thrift IDL service description used to create the client. This typically means the IDL file used by the client is outdated, incorrect, or different from the one used by the server.
fixVerify that the Thrift IDL file used to generate the client is correct and includes the method `yourMethodName` in its `service` definition. Ensure consistency between the client's and server's IDL files and re-parse/re-initialize the client with the correct IDL.
Upgrade
Version history
0.7.0latest on PyPI · released Aug 9, 2026
Audit
Dependencies
plyrequiredRequired for parsing Thrift IDL files.
typing-extensionsrequiredProvides backported and experimental type hints.
cythonoptionalOptional for improved performance of binary and compact protocols.