Install TopologicPy.
One step at a time.

Before you start

You will finish with a notebook that creates and displays a 3D box. You do not need to know Python first. Work through the steps in order and check the result after each one.

This path is for Windows 11 on an Intel or AMD 64-bit computer. Open Windows Settings → System → About and check System type: it should say x64-based processor. Windows on ARM, macOS and Linux need different installation choices; do not use the Windows x64 installer on those systems.

Allow roughly an hour, a reliable internet connection and several gigabytes of free disk space. On a work or university computer, use your organisation’s approved installation process if software installation is restricted.

The commands below use Python 3.12, PythonOCC 8.0.1.1 and TopologicPy 0.9.87 as a fixed starting point. A newer version number elsewhere is not a reason to change these commands while following this guide.

1. Install Miniconda

1. Open the official Anaconda downloads page.
2. Find Miniconda, then choose Windows 64-Bit (x86_64) Graphical Installer. Choose the regular installer, rather than a beta installer.
3. Open Downloads in File Explorer. Double-click the downloaded .exe file.
4. Read the licence terms. If you agree, continue and choose Just Me.
5. Keep the suggested user installation folder. Do not put it inside OneDrive, a network drive or Program Files.
6. Leave Create shortcuts selected. Leave Add Miniconda3 to my PATH unselected. You may leave Register Miniconda as my default Python unselected; we will select our Python explicitly.
7. Click Install, wait, then Finish.

You do not need to download a second Python installer. Miniconda supplies Python. Its installer may mention a different Python version: that belongs to its base environment. Step 3 creates Python 3.12 separately. If Miniconda is already installed, open its existing Anaconda Prompt and continue with the next step.

Official reference: Miniconda’s Windows installation instructions.

2. Open the right command window

1. Press the Windows key and type Anaconda Prompt.
2. Open the result associated with Miniconda. Its name may include Miniconda3.
3. Look for (base) at the left of the last line.

A command is a line you give the computer. Click Copy below, click inside Anaconda Prompt, paste with Ctrl + V, then press Enter. Wait until the prompt returns before entering the next command.

Copy only the text in a code box. Do not type (base), a folder path ending in >, or a Python >>> prompt. These commands go into Anaconda Prompt, not a notebook.

conda --version

Check before continuing: A version such as conda 26.x.x appears. The exact number may differ. If Windows says conda is not recognised, return to the Start menu and open Anaconda Prompt, rather than an ordinary command window.

3. Create your TopologicPy toolbox

First check which environments already exist:

conda env list

If you already see an environment named topologicpy, do not delete or overwrite it. See “An environment with this name already exists” below. For a new installation, continue:

conda create --name topologicpy --override-channels --channel conda-forge python=3.12 pythonocc-core=8.0.1.1 pip ipykernel nbformat plotly

The long line is one command; a line wrapping on screen is normal. Conda will work out which packages it needs, then list them. At Proceed ([y]/n)?, type y and press Enter. Downloading and solving may take several minutes. Leave the window open.

This installs the geometry engine from conda-forge. The environment name is topologicpy; the PythonOCC package name is pythonocc-core. They are different things.

conda activate topologicpy

Check before continuing: The prompt now starts with (topologicpy). If the create command ended in an error, stop and use the troubleshooting section instead of continuing.

Official reference: Conda environments.

Official reference: PythonOCC’s conda-forge package.

4. Install TopologicPy and select PythonOCC

Keep using the same Anaconda Prompt. Check it still starts with (topologicpy). Run:

python -m pip install "topologicpy==0.9.87"

Wait for completion. Requirement already satisfied is also a successful result. Next, save the engine choice for this environment:

conda env config vars set TOPOLOGICPY_CORE_BACKEND=pythonocc

Reload the environment so the setting takes effect. Run these two commands separately:

conda deactivate

conda activate topologicpy

Now check the actual engine:

python -c "from topologicpy.Core import Core; print(type(Core.Backend()).__name__)"

Check before continuing: The result must be PythonOCCBackend. If it says TopologicCoreBackend, or shows an error, do not continue yet. See Geometry engine problems.

Check the installed library version:

python -c "from importlib.metadata import version; print(version('topologicpy'))"

Check before continuing: The result is 0.9.87.

Official reference: TopologicPy installation.

Official reference: Conda environment settings.

5. Give Jupyter a recognisable Python name

Still in Anaconda Prompt, with (topologicpy) showing, run this one command:

python -m ipykernel install --user --name topologicpy --display-name "Python (TopologicPy)" --env TOPOLOGICPY_CORE_BACKEND pythonocc

This registers Python (TopologicPy) in notebook menus. It also gives that notebook kernel the PythonOCC setting, even when VS Code is opened from the Start menu. It does not install another Python.

Check before continuing: A message beginning Installed kernelspec topologicpy appears. The folder shown after it can vary.

Official reference: Installing a notebook kernel.

Official reference: IPython kernel installation options.

6. Install Visual Studio Code

1. Open Microsoft’s VS Code download page.
2. Choose the Windows x64 User Installer.
3. Open the downloaded file, review the licence and follow the installer.
4. Keep Add to PATH selected if offered. This is VS Code’s installer setting; it is different from the Miniconda PATH setting above.
5. Finish and launch Visual Studio Code.

You can skip sign-in, Settings Sync, AI and Copilot setup. They are not needed for the notebook in this guide. If VS Code is already installed, open it and continue.

Official reference: VS Code on Windows.

Official reference: Getting started with VS Code.

7. Add the Python and Jupyter extensions

An extension adds a capability to VS Code. Install these inside VS Code, not in Anaconda Prompt.

1. Press Ctrl + Shift + X to open Extensions.
2. Search for ms-python.python. Choose Python, published by Microsoft, and click Install.
3. Search for ms-toolsai.jupyter. Choose Jupyter, published by Microsoft, and click Install.
4. If VS Code asks to reload, accept.

Python may also install Pylance, Python Debugger and Python Environments. Jupyter may add Notebook Renderers and other companion extensions. Let those finish. The Jupyter extension is the editor interface; ipykernel, installed earlier, runs your Python code.

Check before continuing: Both Python and Jupyter say Installed, Disable or Uninstall, rather than Install. If an extension is disabled, enable it.

Official reference: Microsoft’s Python extension.

Official reference: Microsoft’s Jupyter extension.

8. Create a folder and choose your Python

1. Open File Explorer, go to Documents and create a folder called TopologicPy-Learning.
2. In VS Code choose File → Open Folder and select that folder.
3. If Workspace Trust appears, trust this folder that you just created.
4. Press Ctrl + Shift + P. This opens the Command Palette: a search box for editor actions.
5. Type Python: Select Interpreter, press Enter and choose the entry named topologicpy.

If you cannot find it, return to Anaconda Prompt, activate the environment and run:

python -c "import sys; print(sys.executable)"

Copy the printed path ending in envs\topologicpy\python.exe. In VS Code run Python: Select Interpreter again, choose Enter interpreter path → Find, and select that file. If VS Code offers a path entry box instead, paste the path there. Do not select the Python inside the base Miniconda folder.

Check before continuing: The selected Python points to the topologicpy environment. Notebook kernel selection is a separate step, which comes next.

Official reference: Python in VS Code.

9. Open your first notebook

You can download the starter notebook, save it in TopologicPy-Learning, then use File → Open File in VS Code. Or make it yourself:

1. Press Ctrl + Shift + P, type Create: New Jupyter Notebook and select it. Some versions call this Jupyter: Create New Jupyter Notebook.
2. Press Ctrl + S. Save as first-topologicpy.ipynb in TopologicPy-Learning.
3. Click Select Kernel at the upper right. Choose Select Another Kernel → Jupyter Kernels → Python (TopologicPy) if necessary.

If that name is not listed, also look under Python Environments for topologicpy. If neither appears, see Notebook kernel missing. Do not choose base or install a new environment from this menu.

Check before continuing: The upper-right kernel label says Python (TopologicPy) or identifies your topologicpy environment.

Official reference: Notebook kernel selection.

10. Run code and display a box

A notebook cell is a box where you type code. The starter notebook already contains the three cells below. If you created a blank notebook, paste the first box into its first code cell. This time the code belongs in the notebook, not Anaconda Prompt.

import os
os.environ["TOPOLOGICPY_CORE_BACKEND"] = "pythonocc"

import sys
from importlib.metadata import version
from topologicpy.Core import Core

print("Python:", sys.executable)
print("TopologicPy:", version("topologicpy"))
print("Geometry engine:", type(Core.Backend()).__name__)

Click the triangle to the left of the cell, or press Shift + Enter. Wait for it to finish. If asked to trust the downloaded notebook, inspect the cells below before trusting this file.

Check before continuing: The output shows a Python path containing envs\topologicpy, TopologicPy 0.9.87, and Geometry engine: PythonOCCBackend.

Click + Code to add a cell if needed. Paste and run:

from topologicpy.Cell import Cell

box = Cell.Prism(width=2, length=2, height=2)
print("Volume:", Cell.Volume(box))

Check before continuing: The output is Volume: 8.0. The box has sides of length 2. TopologicPy uses your chosen units; if these lengths represent metres, its volume is 8 cubic metres.

Add a third cell and run:

from topologicpy.Plotly import Plotly

data = Plotly.DataByTopology(box)
figure = Plotly.FigureByData(data)
figure.show()

Check before continuing: An interactive box appears. Drag to rotate it and use the mouse wheel to zoom. Save the notebook with Ctrl + S.

Official reference: Running notebook cells.

11. Continue another day

Open VS Code, choose File → Open Folder → TopologicPy-Learning, and open your notebook. Check its kernel is still Python (TopologicPy), then run the cells from the top.

A saved notebook remembers its code and can retain visible output. The Python variables are not restored automatically. After closing or restarting the kernel, run cell 1 before cell 2, and cell 2 before cell 3.

For future command-line work, open Anaconda Prompt and run:

conda activate topologicpy

You do not need to reinstall Miniconda, VS Code or TopologicPy each time. Keep your notebook files in your learning folder; they do not belong inside the Miniconda installation folder.

Continue to Syntopy tutorials ↗

If something goes wrong

Work on the first error you see. Continuing after a failed step usually creates more confusing messages. Copy the complete error text if you need help; never share account passwords or access tokens.