{"id":7794,"library":"TM1py","title":"TM1py","description":"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]","status":"active","version":"2.2.4","language":"python","source_language":"en","source_url":"https://github.com/cubewise-code/tm1py","tags":["tm1","planning analytics","ibm","cubewise","rest api","olap","etl","automation"],"install":[{"cmd":"pip install --upgrade TM1py","lang":"bash","label":"Standard Install"},{"cmd":"pip install --upgrade \"TM1py[pandas]\"","lang":"bash","label":"Install with Pandas support"}],"dependencies":[{"reason":"Runtime environment","package":"python","version":">=3.7"},{"reason":"HTTP client for REST API communication","package":"requests"},{"reason":"Optional, for SSPI (Windows Integrated Authentication)","package":"requests_negotiate_sspi"},{"reason":"Optional, for DataFrame integration with TM1 data","package":"pandas","optional":true},{"reason":"Optional, for graph-related functionality","package":"networkx","optional":true}],"imports":[{"symbol":"TM1Service","correct":"from TM1py.Services import TM1Service"},{"symbol":"Dimension","correct":"from TM1py.Objects import Dimension"},{"symbol":"Cube","correct":"from TM1py.Objects import Cube"}],"quickstart":{"code":"import os\nfrom TM1py.Services import TM1Service\n\n# --- On-premise TM1 Connection ---\nTM1_ADDRESS_ONPREM = os.environ.get('TM1_ADDRESS_ONPREM', 'localhost')\nTM1_PORT_ONPREM = int(os.environ.get('TM1_PORT_ONPREM', '8001'))\nTM1_USER_ONPREM = os.environ.get('TM1_USER_ONPREM', 'admin')\nTM1_PASSWORD_ONPREM = os.environ.get('TM1_PASSWORD_ONPREM', 'apple')\nTM1_SSL_ONPREM = os.environ.get('TM1_SSL_ONPREM', 'True').lower() == 'true'\n\ntry:\n    with TM1Service(\n        address=TM1_ADDRESS_ONPREM,\n        port=TM1_PORT_ONPREM,\n        user=TM1_USER_ONPREM,\n        password=TM1_PASSWORD_ONPREM,\n        ssl=TM1_SSL_ONPREM\n    ) as tm1_onprem:\n        version_onprem = tm1_onprem.server.get_product_version()\n        print(f\"Successfully connected to on-premise TM1: {version_onprem}\")\nexcept Exception as e:\n    print(f\"Failed to connect to on-premise TM1: {e}\")\n\n# --- IBM Planning Analytics Cloud (PAaaS / TM1 v12) Connection ---\n# Note: For PAaaS, typically an API Key is used with 'user=\"apikey\"'\nTM1_BASE_URL_CLOUD = os.environ.get('TM1_BASE_URL_CLOUD', 'https://us-east-1.planninganalytics.saas.ibm.com/api/<TenantId>/v0/tm1/<DatabaseName>/')\nTM1_API_KEY_CLOUD = os.environ.get('TM1_API_KEY_CLOUD', '')\nTM1_IAM_URL_CLOUD = os.environ.get('TM1_IAM_URL_CLOUD', 'https://iam.cloud.ibm.com')\nTM1_TENANT_CLOUD = os.environ.get('TM1_TENANT_CLOUD', '') # Required for API Key authentication\n\nif TM1_API_KEY_CLOUD:\n    try:\n        with TM1Service(\n            base_url=TM1_BASE_URL_CLOUD,\n            user=\"apikey\",\n            password=TM1_API_KEY_CLOUD,\n            iam_url=TM1_IAM_URL_CLOUD,\n            tenant=TM1_TENANT_CLOUD,\n            ssl=True,\n            verify=True,\n            async_requests_mode=True\n        ) as tm1_cloud:\n            version_cloud = tm1_cloud.server.get_product_version()\n            print(f\"Successfully connected to PA Cloud: {version_cloud}\")\n    except Exception as e:\n        print(f\"Failed to connect to PA Cloud: {e}\")\nelse:\n    print(\"Skipping PA Cloud connection: TM1_API_KEY_CLOUD not set.\")","lang":"python","description":"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]"},"warnings":[{"fix":"Review 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]","message":"Connecting 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]","severity":"breaking","affected_versions":"TM1py < 2.0 when connecting to TM1 v12/PAaaS"},{"fix":"Double-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]","message":"Connection 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]","severity":"gotcha","affected_versions":"All"},{"fix":"When 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]","message":"For 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]","severity":"gotcha","affected_versions":"TM1py < 1.11, or 1.11+ without `use_blob=True`"}],"env_vars":null,"search_vec":"'15':76 '2.2.4':66 '3':74 '5':75 'activ':52 'analyt':17,79 'api':20,83 'autom':86 'communiti':58 'contributor':60 'cubewis':55,81 'current':63 'data':43 'develop':30 'enabl':34 'etl':85 'execut':44 'facilit':28 'free':5 'ibm':15,80 'interact':36 'librari':27,50 'like':41 'maintain':53 'manag':47 'metadata':48 'minor':72 'olap':84 'open':8 'open-sourc':7 'packag':11 'plan':16,78 'process':45 'programmat':35 'python':10,29 'reading/writing':42 'receiv':68 'regular':69 'releas':73 'rest':19,82 'simpl':24 'simple-to-us':23 'sourc':9 'task':40 'tm1':18,32,38,77 'tm1py':1,2 'updat':70 'use':26 'version':64 'wrap':13","created_at":"2026-04-16T14:13:41.146282+00:00","updated_at":"2026-04-16T14:13:41.146282+00:00","problems":{"verify_error":"error: unexpected argument '--upgrade TM1py' found\n\n  tip: a similar argument exists: '--upgrade'\n\nUsage: uv pip install --upgrade <PACKAGE|--requirements <REQUIREMENTS>|--editable <EDITABLE>|--group <GROUP>>\n\nFor more information, try '--help'."},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.3.1","cli_name":"","cli_version":null,"type":"library","homepage":"https://www.cubewise.com/tm1py","github":"https://github.com/cubewise-code/tm1py","docs":null,"changelog":null,"pypi":"https://pypi.org/project/TM1py/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","data","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"install_fail","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-05","install_tag":null}}