Installing TM1py

This article explains the steps to install TM1py. Installing TM1py will take you just few minutes.


  • TM1 (10.2.2 Fix Pack 5 or higher)

Checking if Python is installed

TM1py is a Python package, in order to use TM1py you need to install Python. First, we need to check if you have python installed. Open the command-line and type:

  • python --version.

To open the command-line, press the windows button on the keyboard. Then type 'cmd'. Then press enter.

If you are getting the message above, it means that Python is not installed. If Python is already installed you can just use pip install TM1py to install the TM1py package.

Installing Python or Anaconda

To install Python you can choose to either install the official Python platform or another Python platform such as Anaconda. We recommend installing Anaconda as it contains Python + a lot of very useful libraries such as Jupyter Notebook:

To get the latest Anaconda version click the following link:

Choose the correct distribution:

Once downloaded just execute the installer, you can keep the default settings and click next until the end of the installer (The installation should take less than 10 minutes):

Installing TM1py

To install TM1py with Anaconda, just open the Anaconda prompt:

and then type the following command line:

  • pip install TM1py

Check connectivity with your TM1 instance

Once TM1py installed, you need to check the connectivity with your IBM TM1 or Planning Analytics instances, to do that just follow the steps described in the following article:

Installing TM1py on a server with no internet connection

This article describes the step to install TM1py on a server with no internet connection.

1 - Download Python or Anaconda

TM1py is a Python package, it requires either Python or Anaconda (A platform to manage your Python packageds) to be installed first:

2 - Install Python or Anaconda

Once downloaded copy the installer into your server and follow the installer steps. In this article we chose to install Anaconda.

3 - Check if Anaconda is installed correctly

Open the Anaconda command promtp and type:

  • where Python

It will return the path where Python is installed.

4 - Install TM1py

All TM1py version can be found in the GitHub repository:

Download the source code:

Unzip it and copy the TM1py folder:

Then you paste the TM1py folder into C:\ProgramData\Anaconda3\Lib\site-packages (or wherever the install-directory of python / Anaconda is located on that machine).

Then in the TM1py directory inside the lib\site-packages folder it should look exactly as in the lib\site-packages\TM1py folder on your local machine, where you installed TM1py through pip.

Setup Cubike example

Cubike is a fictional Bike Sharing company that we use the series of articless about Data Science with TM1 and Planning Analytics:

If you are new to TM1py, this article will guide you to setup TM1py and all the different modules required in the Cubike example.


The only prerequisite is to have IBM TM1 10.2.2 FP5 as minimum already installed. For this example we are going to work with the TM1 instance called tm1srv01:


1. Install Python

TM1py is a python package. To install TM1py, we need first to install Python. The steps to install Python can be found here:

Once Python has been installed, to check if the installation was successful. Open a command line as administrator:

and then type the following command to get the Python version:

Python --version

In this example the Python version is v3.6.2:


2. Install TM1py

First you need to navigate to the Scripts folder where Python has been installed. To find out the Python location, in a Windows command promt type:

where Python

It should return you the location:

To go to the Python location just type cd and then the folder location:

cd "C:\Python36\Scripts"

To install TM1py you just need the following command line:

pip install TM1py

To check if the installation was successful just type:

pip show TM1py

It is going to show you information about TM1py and the version number, in this example v1.0.2:


3. Enabling TM1 REST API

TM1py uses the TM1 REST API to connect to the TM1 instance. In this example, our tm1srv01 instance uses the port 17001 for the REST API. To find out which port your TM1 instance is using, open the tm1s.cfg file and check the HttpPortNumber value.

To enable the REST API, open a web browser and paste the following URL:

  • https://localhost:17001/api/v1/$metadata 

You should be prompted this warning message, click Advanced and then Proceed to localhost (unsafe):

You should then see the metadata information of your TM1 instance:


4. Test connection with TM1

Once the TM1 REST API has been enabled, the next step is to check if you have the right TM1 settings to connect to your TM1 instance. Just follow steps described in the following article:

After running the script from the TM1py samples, TM1py should be able to find your TM1 instance name:


5. Download Cubike example

All the files you need to go through the Cubike examples are gathered in one zip file which you can download here:

After unzipping this file, you should see two Jupyter notebooks, four csv files and one python script:

  • chicago.csv: Bike Sharing data from Chicago.+
  • Data Integration with TM1py.ipynb: Jupyter Notebook to load data into TM1 from a web service.
  • Data Science with TM1py.ipynb: Jupyter Notebook to analyse the data.
  • nyc.csv: Bike Sharing data from New Yord City.
  • public holidays.csv: Public Holidays data.
  • washington_dc.csv: Bike Sharing data from Washington DC.
  • Python script to create TM1 objects.

6. Install Jupyter Notebook

For demonstration and documentation purposes all the python code in this series is distributed through Jupyter Notebooks. Jupyter Notebooks allow you to create and share documents that contain live code, equations, visualizations and narrative text. A quick introduciton to Jupyter can be found here.

This example contains two Jupyter notebook (.ipynb). To open these two notebook, we have to install Jupyter first.

To install Jupyter, you just need to run the following command from the Scripts Python folder:

pip install jupyter

7. Open a Jupyter Notebook

To open Jupyter Notebook, you need to run Jupyter. To open a Windows command prompt, go to the folder location where you downloaded the Cubike example and then in the Windows Explorer bar, just type cmd and press enter:

To run Jupyter from this location, just type:

jupyter notebook

A new tab on your web browser should open and you should be able to see the two Jupyter Notebooks (.ipynb) file, just click on the first one to open it:

Once opened, you can then use the buttons at the top to navigate through the code's blocks. The most important button are the Up/Down arrow and the Run button which executes a code block and go to the next one:


Other Python packages required for Part 2 and Part 3 articles:

To run the Data Science with TM1py.ipynb, you will need to install in the Python folder, the following packages:

1) Ploty is a graphing library

pip install plotly

2) C++ Compiler is required by Facebook Prophet, you can download it from Build Tools for Visual Studio 2017 and run as administrator .exe file.

A restart of the server will be required.

3) Msgpack: (required by Facebook Prophet):

pip install msgpack-python

4) PyStan (required by Facebook Prophet)

pip install PyStan

5) Facebook Prophet is a forecasting tool.

pip install fbprophet

6) Matplotlib is a plotting library

python -mpip install -U matplotlib

Cubike Part1

You are now ready to start the Part 1 article:



+ What is TM1py ?

TM1py is a Python package that wraps the TM1 REST API in a simple to use library. That makes it easy to build stuff with TM1 and python.

+ What is Python ?

Python is a widely-used general-purpose programming language that lets you work quickly and integrate systems more effectively.

+ Why you should use TM1py ?

  • Use Pandas for Data Analysis and Statistics on top of your TM1 model.
  • Load data (e.g. FX, stock data) from web services into TM1 such as Quandl financial.
  • Build Machine Learning and Forecasting Algorithms with Python and scikit-learn based on your TM1 data.

+ TM1py prerequisites ?

TM1 server should be on version 10.2.2 FP5 as minimum.

+ Do I need a license to use TM1py ?

TM1py is a free and open source (MIT license) and there are no limitations of any kind. All of the code, documents and information in TM1py are to be deemed without warranty.

+ What TM1 security does TM1py support ?

TM1py supports TM1 Security mode 1, 2, 4 and 5. TM1py supports CAM authentication which allows any LDAP directory to be used including the Active Directory.

+ How can I contribute?

The source code is hosted at If you find a bug or feel like you can contribute please fork the repository, update the code and then create a pull request so we can merge in the changes.

+ How do I get started ?

Just follow this Quick startup guide and you will be able to run your first Python script in less than 5 min.

Set up jupyter notebook

Jupyter is an open-source web application that enables you to mix code-execution and comments. It is great to tell a story and run through the code sections by sections.

The main difference with pycharm is that jupyter allows you to execute your python scripts sections by sections.

Why you should use it:

  • Jupyter notebook is a web app, that allows us to write code in a more narrative, interactive way.

  • You can share notebooks through mails or host them at a shared platform.

  • Jupyter Notebooks are a great, new way to tell a story with your TM1 Data.

Download Jupyter

Run jupyter notebook

Run in a command line:

  • jupyter notebook

Jupyter is running by default on the 8888 port. To access the notebook, go to the following url:

  • http://localhost:8888


Check Connectivity with TM1

In order to check if TM1py can connect to your TM1 instance, you can use the Python script from the samples. First download the samples from Github and then navigate to the TM1py-samples folder that you downloaded from Github, in this example the samples are located in the following folder:

  • C:\TM1py\TM1py-samples-master

Hold shift and right-click in the folder. Then select "Open command window here". This should open the command-line (or PowerShell depending on your Windows version). Now type "python" into the console to execute the script.

  • python

The script will ask you for:

  • TM1 User (Name of the TM1 User)

  • Password (The user's password. The command-line reads your input silently)

  • CAM Namespace:

  • Port (The HTTPPortNumber as specified in the TM1s.cfg)

  • address (Address of the TM1 instance. 'localhost' or '' if you run the TM1 instance locally)

  • ssl (True or False, as stated in the TM1s.cfg)

TM1py will then try to connect to your TM1 instance.

It will print out the name of the TM1 instance. If this works without Errors you should be able run any of the samples.

If this does not work you should check:

  1. If the TM1 REST API is enabled

  2. Double check your credentials as the CAM Namespace is case sensitive

All the samples are based on the Planning Sample TM1 model, that comes with the installation of TM1. The samples potentially contain hard coded references to TM1 objects (e.g. cube names). Make sure to adjust those references if you are not testing against the Planning Sample!

Set up your development environment

To use TM1py samples, you do not have to have a development environment, you can just edit the script in a text editor or in jupyter and then run the script. But if you want to dig deeper into the Python language, having a development environment will make your life easier.

Why do you need a development environment?

  • If you want to explore the TM1py code.
  • See the TM1py scripts in multiple windows.
  • Edit and run your scripts in the same interface.
  • Code-completion and syntax highlightning.


PyCharm is likely the best IDE for Python. It offers intelligent code completion, on-the-fly error checking and heaps of other features. It allows you to save time and be more productive. IntelliJ offers a free Community Edition of PyCharm:

Once downloaded and installed with the default settings, you just need to locate the folder where you have downloaded the TM1py samples:


You are now good to go!

The following video will give you a quick tour to the PyCharm main features:

Run TM1py script from TM1 process

This article explains the steps to run a TM1py script from TM1 process.

1. Locate python.exe

First you need to locate python.exe file. The first locations to look at are:

  • C:\Python36
  • C:\Users\(Your logged in User)\AppData\Local\Programs\Python\Python36

If you can't find your python.exe location, you can just type in a command line:

  • where python

In this example python.exe is located in C:\Python36\python.exe.

2. Locate the Python script

The script we want to run is 

  • C:\TM1py\TM1py-samples-master\Load Data\fx rates to

3. Create TM1 process

To run a python script from a TM1 process, we are going to use the ExecuteCommand function of the TM1process:

  • ExecuteCommand(CommandLine, Wait);

The ExecuteCommand function has two parameters:

  • CommandLine will be the path of the python.exe and the script.
  • Set Wait to 1 if you want the TM1 process to wait for the script to finish Wait to 0, if you want the process to go straight to the next line.

Create a new TM1 process and add the following code:

pyExe = '"C:\Python36\python.exe"' ;

pyFile = '"C:\TM1py\TM1py-samples-master\Load Data\fx rates to cube"' ;

EXECUTECOMMAND(pyExe |' '| pyFile,1);

Because there are spaces in the script name, we need to add double quotes "" inside the single quotes.

Save the process and run it.

If there is an error in the command line, you won't be able to see it from the TM1 process. Even if the TM1 process runs successfully, the command line could fail. You can check your command line in the command window:

  • "C:\Python36\python.exe" "C:\TM1py\TM1py-samples-master\Load Data\fx rates to cube"

If you are planning to run multiple scripts, it is a good practice to store the file locations in a TM1 cube, so you can easily update the file locations if you need to.

You can access the code of the script used in this example, fx rates to cube on Github.

Create TM1 objects for TM1py samples

All the TM1py scripts in the Load Data folder requires some TM1 objects. These scripts load data from different datasources into TM1 cubes. If you want to test these scripts without changing the target cubes, you will need to create these TM1 objects.
To create these objects, you can run the script sample which is in the Load Data folder:

1. Update TM1 instance settings

Before running the script you open the sample script and update the TM1 instance connection settings:

2. Run the script

To run the script, just type the following command line:

  • python "sample"

If the command line shows errors it could be either because you are not running the script in the right folder or tm1py can't connect to the TM1 instance. Check if the connection with TM1 works.

3. Check the new TM1 objects

if the script ran successfully, you will then be able to see the following three cubes in your TM1 instance:

Check TM1py version

Check TM1py version using the command line

To check the TM1py version installed on your machine, just open a command window and then type:

  • pip show TM1py

In the example above the TM1py version is 0.1.1

Check TM1py version using PyCharm

If you are using PyCharm, to check the TM1py version you need to go to File > Settings, click on your project and you should see all the packages that the package is using. In the example below the TM1py version is 1.0.1:

Install TM1py

TM1py is a Python package that wraps the TM1 REST API in a simple to use library. That makes it easy to build stuff with TM1 and python.


  • TM1 10.2.2 FP5 as minimum

It is very easy to set up TM1py, you just need to follow these three steps:

  1. Install Python
  2. Enable the TM1 REST API
  3. Install TM1py package

All these steps are defined in the TM1py-sample github page: