TM1py is a free and open-source Python package that wraps the IBM Planning Analytics (TM1) REST API into a simple-to-use library, facilitating Python developments for TM1. It enables programmatic interaction with TM1 for tasks like reading/writing data, executing processes, and managing metadata. The library is actively maintained by Cubewise and a community of contributors, with the current version being 2.2.4, and receives regular updates and minor releases. [3, 5, 15]
Install & Compatibility
Where this runs
tested against v2.3.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.940 runs
installs and imports cleanly · install 0.0s · import 1.423s · 26.6MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 7.3s · import 1.303s · 27MB
25MB installed
● package 25MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TM1Service
✓ from TM1py.Services import TM1Service
Dimension
✓ from TM1py.Objects import Dimension
Cube
✓ from TM1py.Objects import Cube
This quickstart demonstrates how to establish a connection to an on-premise TM1 instance and an IBM Planning Analytics Cloud (PAaaS) instance using TM1py. It retrieves the server product version to confirm connectivity. Environment variables are used for sensitive credentials. For PAaaS, a `base_url`, `api_key`, `iam_url`, and `tenant` are typically required for API Key authentication. [5, 18]
import os
from TM1py.Services import TM1Service
# --- On-premise TM1 Connection ---
TM1_ADDRESS_ONPREM = os.environ.get('TM1_ADDRESS_ONPREM', 'localhost')
TM1_PORT_ONPREM = int(os.environ.get('TM1_PORT_ONPREM', '8001'))
TM1_USER_ONPREM = os.environ.get('TM1_USER_ONPREM', 'admin')
TM1_PASSWORD_ONPREM = os.environ.get('TM1_PASSWORD_ONPREM', 'apple')
TM1_SSL_ONPREM = os.environ.get('TM1_SSL_ONPREM', 'True').lower() == 'true'
try:
with TM1Service(
address=TM1_ADDRESS_ONPREM,
port=TM1_PORT_ONPREM,
user=TM1_USER_ONPREM,
password=TM1_PASSWORD_ONPREM,
ssl=TM1_SSL_ONPREM
) as tm1_onprem:
version_onprem = tm1_onprem.server.get_product_version()
print(f"Successfully connected to on-premise TM1: {version_onprem}")
except Exception as e:
print(f"Failed to connect to on-premise TM1: {e}")
# --- IBM Planning Analytics Cloud (PAaaS / TM1 v12) Connection ---
# Note: For PAaaS, typically an API Key is used with 'user="apikey"'
TM1_BASE_URL_CLOUD = os.environ.get('TM1_BASE_URL_CLOUD', 'https://us-east-1.planninganalytics.saas.ibm.com/api/<TenantId>/v0/tm1/<DatabaseName>/')
TM1_API_KEY_CLOUD = os.environ.get('TM1_API_KEY_CLOUD', '')
TM1_IAM_URL_CLOUD = os.environ.get('TM1_IAM_URL_CLOUD', 'https://iam.cloud.ibm.com')
TM1_TENANT_CLOUD = os.environ.get('TM1_TENANT_CLOUD', '') # Required for API Key authentication
if TM1_API_KEY_CLOUD:
try:
with TM1Service(
base_url=TM1_BASE_URL_CLOUD,
user="apikey",
password=TM1_API_KEY_CLOUD,
iam_url=TM1_IAM_URL_CLOUD,
tenant=TM1_TENANT_CLOUD,
ssl=True,
verify=True,
async_requests_mode=True
) as tm1_cloud:
version_cloud = tm1_cloud.server.get_product_version()
print(f"Successfully connected to PA Cloud: {version_cloud}")
except Exception as e:
print(f"Failed to connect to PA Cloud: {e}")
else:
print("Skipping PA Cloud connection: TM1_API_KEY_CLOUD not set.")
Debug
Known issues
breakingConnecting to TM1 v12/Planning Analytics as a Service (PAaaS) requires a different set of parameters (e.g., `base_url`, `api_key`, `iam_url`, `tenant`) compared to older on-premise TM1 versions. Existing connection patterns for PAaaS will break if not updated to the new authentication scheme introduced around TM1py 2.0. [5, 15]fixReview the TM1py documentation for v12/PAaaS connection specifics. Use `base_url`, `user='apikey'`, `password=api_key`, `iam_url`, and `tenant` parameters in `TM1Service` for PAaaS instances. [5, 18]
affects: TM1py < 2.0 when connecting to TM1 v12/PAaaS
gotchaConnection issues are common due to incorrect `TM1Service` parameters (address, port, SSL, user, password, namespace, etc.) or if the TM1 REST API is not correctly enabled on the TM1 server. SSL errors (`SSLError`, `SSLV3_ALERT_HANDSHAKE_FAILURE`) often indicate certificate issues or misconfigured `ssl` / `verify` parameters. [9, 12, 17]fixDouble-check all `TM1Service` parameters against your TM1 server configuration (e.g., `tm1s.cfg` for HTTPPortNumber, UseSSL). Ensure the TM1 REST API is enabled. For SSL errors, try setting `verify=False` (though not recommended for production) or provide the correct path to your `.cer` file for `verify`. [10, 16, 17]
affects: All
gotchaFor large read/write operations (e.g., `write` or `write_dataframe`), not utilizing the `use_blob=True` parameter can lead to significantly slower performance compared to using optimized modes available in TM1py v1.11 onwards. [19]fixWhen performing bulk data operations, especially with pandas DataFrames, pass `use_blob=True` to `tm1.cells.write()` or `tm1.cells.write_dataframe()` for improved performance. [19]
affects: TM1py < 1.11, or 1.11+ without `use_blob=True`
Audit
Dependencies
pythonrequiredRuntime environment
requestsrequiredHTTP client for REST API communication
requests_negotiate_sspirequiredOptional, for SSPI (Windows Integrated Authentication)
pandasoptionalOptional, for DataFrame integration with TM1 data
networkxoptionalOptional, for graph-related functionality