9.1 Environment Setup

Introduction

Every lesson before this one in the Knowledge Hub has been about reading, reasoning about, or checking an IFC file by hand, opening it in a viewer, tracing a property by eye, running it through a validator someone else built. This lesson starts a different track: writing the code that reads an IFC file directly. Before any of that logic makes sense, the right library needs to be installed correctly, and this is one of those areas where a wrong first step costs real time later. This lesson covers exactly that, nothing more, no IFC logic yet.

What's Actually Needed

Two things: Python itself, and IfcOpenShell installed as a library inside it. IfcOpenShell is an open-source library, LGPL licensed, built for reading, writing, and querying IFC files, with both a C++ core and Python bindings that expose the full API. It doesn't require Blender or Bonsai to be installed. Bonsai bundles IfcOpenShell inside itself, an add-on that turns Blender into a graphical IFC authoring platform, giving non-programmers a working Python console without installing anything separately. That's one route among several, and it isn't the one this module uses. Writing scripts against plain Python and a directly installed IfcOpenShell is the route that generalizes: a script written this way can be deployed wherever a compatible Python and IfcOpenShell environment is available, in an automated pipeline, on a server, in a scheduled job, without a graphical application sitting underneath it.

Installing IfcOpenShell

IfcOpenShell's own documentation lists several installation routes and recommends one specifically for this situation: PyPI, Python's standard package index, is the recommended method for anyone using pip, the standard tool for installing Python libraries.

Worth running one command first, since a machine can have more than one Python installation, and pip on its own doesn't always point at the interpreter a person thinks it does:

python --version

That confirms which Python is actually active. Then install using that same interpreter explicitly:

python -m pip install ifcopenshell

Writing it as python -m pip rather than just pip tells the specific Python interpreter just checked to run its own pip, rather than leaving it to chance which installation on the system actually receives the package. This detail becomes directly relevant in the next section, since a mismatch here is exactly what causes some install failures.

The First Sanity Check

Before writing anything that touches a real IFC file, it's worth confirming the install actually worked. IfcOpenShell's own documentation includes this check as part of its installation instructions:

import ifcopenshell
print(ifcopenshell.version)
model = ifcopenshell.file()

Each line confirms something progressively stronger than the last. The first confirms Python can locate and load the module at all. The second confirms the module exposes its own version information, useful to have on hand later if something behaves unexpectedly and version turns out to matter. The third actually instantiates IfcOpenShell's core file object, a blank, empty in-memory model, not from a real file yet, just proof that the library's central object genuinely works rather than merely importing without error. If all three lines run clean, the install is confirmed working, and there's nothing IFC-specific left to troubleshoot before moving on.

Common Install Failures

A few things go wrong often enough to be worth naming directly, rather than discovering them the hard way.

The most common one isn't really an installation failure at all. It's installing the wrong package. A similarly named package, install-ifcopenshell-python, also exists on PyPI, a separate, unofficial helper project, not the official ifcopenshell distribution this module is built around. The name similarity is the actual trap: typing something close but not exact is an easy mistake, and it installs a different codebase entirely. The correct package name for everything in this module is exactly ifcopenshell, nothing appended, nothing rearranged.

The second is a Python version mismatch, and it can run in either direction. Current as of August 2026, IfcOpenShell 0.8.5 requires Python 3.10 through 3.14, with prebuilt packages published for each of those versions across major platforms. That range will keep moving as new releases come out, and it's worth checking the current supported range directly rather than assuming this article's numbers hold indefinitely. The direction worth watching for specifically is a brand-new Python release outpacing IfcOpenShell's support. When a new major Python version ships, there's often a real gap before a compatible IfcOpenShell package follows, and installing during that gap produces an error reporting no matching distribution was found. If that happens, the fix isn't to keep retrying the same command, it's to check IfcOpenShell's current documentation for its supported range and, if needed, use a slightly older, fully supported Python version instead.

The third shows up mainly on Windows: an install that starts building a component called mathutils from source and then fails with a compiler-related error, sometimes specifically asking for Microsoft's C++ Build Tools. This happens when pip can't find a prebuilt package matching the exact Python version and system in use, and falls back to compiling from source instead, a fallback that needs compiler tools most machines don't have installed by default. Using a Python version inside IfcOpenShell's currently supported range usually avoids this entirely, since a supported version normally has a prebuilt package ready and never needs the source-build fallback.

What's Next

With the library installed and confirmed working, the next lesson moves to the part this one deliberately held back: opening a real IFC file and reading something out of it for the first time.