Install & Compatibility
Where this runs
tested against v0.13.1 · 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 2.736s · 686.9MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 17.3s · import 2.570s · 644MB
683MB installed
● package 683MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ODPS
✓ from odps import ODPS
The core entry point for interacting with MaxCompute (ODPS) services.
DataFrame
✓ from odps.df import DataFrame
Used for the pandas-like DataFrame API for data analysis on MaxCompute.
options
✓ from odps import options
Global configuration options for PyODPS behavior, e.g., enabling interactive mode or schema support.
This quickstart demonstrates how to initialize the `ODPS` object using environment variables for credentials and then access a MaxCompute table (`dual`) to inspect its schema and read a few records. Replace placeholder values like 'your-project' and 'your-endpoint' with your actual MaxCompute project and endpoint. It's highly recommended to use environment variables for sensitive credentials.
import os
from odps import ODPS
# Ensure environment variables are set for security and best practice
# ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET
access_id = os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_ID', 'your-access-id')
secret_access_key = os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_SECRET', 'your-secret-access-key')
project = os.environ.get('ODPS_PROJECT', 'your-project')
endpoint = os.environ.get('ODPS_ENDPOINT', 'your-endpoint')
# Initialize ODPS object
o = ODPS(access_id, secret_access_key, project=project, endpoint=endpoint)
# Get a table object
table = o.get_table('dual')
# Print table schema details
print(f"Table Name: {table.name}")
print(f"Table Schema: {table.table_schema}")
print("First 5 records:")
with table.open_reader() as reader:
for record in reader.read(5):
print(record)
odps --version
Debug
Known issues
breakingThe class `odps.accounts.AliyunAccount` was renamed to `odps.account.CloudAccount`. Code directly importing or referencing the old name will break.fixUpdate your imports from `from odps.accounts import AliyunAccount` to `from odps.account import CloudAccount`.
affects: >=0.12.4
breakingMaxCompute V4 signature is enabled by default, which may cause issues with services or environments that do not support it.fixIf your service does not support V4 signatures, you might need to explicitly configure PyODPS to use an older signature version, if such an option is available and supported by your MaxCompute instance.
affects: >=0.12.4
breakingDecimal precision and scale checks at the client side have been tightened to align with MaxCompute server-side behavior. This might cause existing client-side checks to fail that previously passed.fixReview and adjust your data handling logic involving decimal types to ensure they conform to the stricter precision and scale rules.
affects: >=0.12.5
gotchaWhen using third-party packages in Python UDFs for MaxCompute, import statements for these packages must be placed *inside* the UDF's `evaluate` method (or similar processing method). Placing them at the module level will lead to runtime errors because the package is only available within the execution context on the MaxCompute server.fixMove `import` statements for third-party libraries into the `evaluate` or `process` method of your UDF class. Ensure the third-party package is uploaded as an archive resource to MaxCompute.
affects: All versions when using UDFs with third-party packages
gotchaPyODPS `execute_sql()` or `run_sql()` methods are primarily for DQL (Data Query Language) and DML (Data Manipulation Language). They may not correctly execute all SQL statement types, particularly DDL (Data Definition Language) commands like `CREATE TABLE` or complex API commands.fixFor DDL operations (e.g., `CREATE TABLE`, `DROP TABLE`), use the specific PyODPS methods on the `ODPS` object (e.g., `o.create_table()`, `o.delete_table()`). For API commands, use corresponding PyODPS API methods.
affects: All versions
gotchaDownloading large datasets entirely to a local machine using PyODPS can lead to Out-Of-Memory (OOM) errors, especially when dealing with MaxCompute's distributed nature.fixIt is highly recommended to offload heavy data processing and computations to the MaxCompute cluster by leveraging PyODPS DataFrame API or MaxCompute SQL. Only download aggregated or sampled results to your local environment.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'odps'
The user is attempting to import from 'odps' which is not the correct top-level package name for the PyODPS library.
fixfrom pyodps import ODPS
odps.errors.ODPSError: 401 Unauthorized
The provided MaxCompute access ID or secret access key is incorrect, expired, or lacks the necessary permissions to access the specified project.
fixEnsure the `access_id` and `secret_access_key` parameters are correct and have appropriate permissions during `ODPS` object initialization.
AttributeError: 'DataFrame' object has no attribute 'to_sql'
PyODPS DataFrame objects are distinct from Pandas DataFrames and do not possess a `to_sql` method for direct SQL database interaction.
fixTo persist data to MaxCompute, use `df.persist()`. If converting to a local SQL database, first convert to a pandas DataFrame: `df.to_pandas().to_sql(...)`.
pip install odps
The user is attempting to install the library using the incorrect package name 'odps' instead of the correct package name 'pyodps'.
Upgrade
Version history
0.13.1latest on PyPI · released Aug 14, 2026
Audit
Dependencies
setuptoolsrequiredRequired for package installation and metadata handling.
requestsrequiredHTTP client for API communication.
sixrequiredPython 2 and 3 compatibility utilities.
protobufrequiredUsed for data serialization.