Python in Grasshopper

Grasshopper solves problems by wiring components together, and for a huge range of parametric work that is faster and clearer than code. So why script at all? Because some things the visual graph does badly. Iterative logic - where each step depends on the last - is painful to wire but trivial to write as a for loop. Conditional branching - do this if a room is over 15 sqm, otherwise that - sprawls into a mess of Stream Filter and Dispatch components but reads as three lines of Python. And sometimes you simply know the code already and reaching for a component you half-remember is slower than typing what you mean.

The honest rule is: use components for the flow, drop to code for the knots. A mature Grasshopper definition is usually mostly components with a few script components at the awkward joints - not one giant script that ignores the canvas, and not a heroic all-visual contraption avoiding code on principle. You are not choosing sides; you are using the right tool for each stretch. This whole module lives at that boundary, and it starts with the mechanics of getting data in and out of a script component cleanly.

There is also a quieter reason to script inside Grasshopper: reuse and clarity. A component someone wired up two years ago is a puzzle to inherit - you have to trace every wire to understand it. A short, well-named script with a comment at the top often explains itself, and you can copy it between definitions without re-wiring anything. Once you are comfortable, a script component becomes a little reusable tool you carry from project to project: your own averaging component, your own labeller, your own bay-grid maker. That personal toolkit, built up over time, is one of the real dividends of learning to script rather than only to wire.

Be honest about the flip side, though: a script component is a black box on the canvas. Where a chain of components shows its working at every step - you can hover any wire and see the data - a script hides its logic inside, visible only if someone opens it. That is a fair trade for a knotty calculation, and a poor one for something a Dispatch and a Cull would show plainly. The skill is knowing which is which, and it is why this lesson keeps returning to the same rule: reach for code when it genuinely reads more clearly than the wires, not merely because you can.

Being precise here saves confusion later, because Grasshopper has had two Python engines. The older GHPython component runs IronPython 2.7 - an implementation of the now-ancient Python 2 built on .NET. It is still around in older files and still works, but Python 2 has been end-of-life for years and you should not start new work in it.

Since Rhino 8, Grasshopper ships a new Python 3 script component running real CPython 3 - the same Python you install from python.org. This matters enormously: it means you can pip install normal libraries like numpy or pandas and use them right inside Grasshopper, which the old IronPython engine could not do cleanly. Throughout this module, the script component means this modern CPython 3 one unless stated otherwise.

Either way, one thing is constant: your code runs with access to Rhino's geometry library. Inside the component you typically write:

import Rhino.Geometry as rg

pt = rg.Point3d(3.0, 5.0, 0.0)
vec = rg.Vector3d(0, 0, 10)

Rhino.Geometry is part of RhinoCommon, Rhino's full geometry SDK, and it is what lets your script make points, curves and surfaces that the rest of the canvas understands. We meet it properly in lesson 6.3.

One practical consequence of the CPython 3 shift is worth flagging now, because it will save you a confusing hour later. Because the new component is real CPython, code you write and test in a normal editor - or that an AI assistant generates - runs the same way inside Grasshopper, which was never quite true of the old IronPython. Standard-library modules like math, random, csv and json all behave exactly as they do everywhere else in this course. The main things unique to the Grasshopper context are the Rhino.Geometry types and the input/output plumbing; the plain Python underneath is just Python. That continuity is the reason this course teaches the language first and the tools second - the fundamentals genuinely transfer.

Here is the core mechanic, and it is beautifully simple. Every input on the script component becomes a variable in your code, named after the param. The defaults are x and y; rename the param to radius and a variable radius appears. Every output is a name your code assigns to; the default output is a. Whatever you store in a gets pushed back onto the canvas through that wire.

So the smallest useful script is genuinely this:

# inputs on the component: x, y
# output on the component: a
a = x + y

Wire two number sliders into x and y, and a carries their sum out. Add a second output param named b, and you can return two things:

a = x + y
b = x * y

The values can be anything Python holds - numbers, strings, lists, or Rhino geometry. This is the whole contract between code and canvas: read the inputs as variables, do your work, assign the outputs by name. There is no return, no print to the wires - just assignment. Forgetting to assign an output is the single most common beginner slip: the code runs, but the output param stays empty because nothing was ever put in a.

A subtle but important point: the output can hold a whole collection, not just one value. If you assign a Python list to a, Grasshopper unpacks it into a list on the wire, so one script can emit many items:

a = [rg.Point3d(i, 0, 0) for i in range(10)]   # ten points out

That list comprehension - straight from Module 2 - builds ten points and sends them all through the single output a. This is how a script becomes a generator of geometry rather than a calculator of one number, and it is the pattern behind every worked example later in this module. Assign a single value and you get one item on the wire; assign a list and you get many.

One setting changes everything about how your script behaves: the access mode of each input, set by right-clicking the param. There are three choices.

Item access (the default) hands your code one value at a time and runs the whole script once for each item. If you wire in a list of ten numbers with x set to Item access, your script executes ten times, with x being a single number each run. Simple, but you cannot see the other items - no totals, no sorting, no looking at neighbours.

List access hands your code the entire list in one run, as a real Python list. Now x might be [3, 5, 8] and you can do list things:

# x set to List access
a = sum(x) / len(x)   # the average

Tree access hands you the whole Grasshopper data tree - every branch - which we unpack in lesson 6.4. The guidance is to reach for the simplest mode the task allows: Item when each value is independent, List when you need to see a whole branch together, Tree only when the branch structure itself matters. Getting this choice right is often the difference between a script that works and one that quietly does the wrong thing to the wrong number of items.

There is a matching setting on the output side, called the output type or list access on the output, but the everyday rule is simpler than the inputs: if you assign a list, you get a list out. The one habit worth forming early is to decide the access mode deliberately for every input, rather than accepting the Item default and wondering why your averaging script keeps returning a list of unchanged numbers. When a script behaves strangely, the access modes are the first thing to check - more often than not, an input that should be List is still set to Item, so your code is being run once per value and never sees the collection it needs. We return to the fullest mode, Tree access, in lesson 6.4, once trees themselves make sense.