Grasshopper Python 3 Guide: Data Access, Type Hints, and Outputs

This guide is based on Rhino’s developer documentation for Grasshopper Python scripting, updated on 29 September 2026. You can add a Python 3 or IronPython 2 Script component in Grasshopper, or select Python 3 from the language menu in the general Script component. The steps below focus on configuring the component’s inputs, data access, and outputs before generating geometry. The documentation notes that some options depend on the Rhino version; for example, the option to make an input parameter required is available as of Rhino 8.14.

1. Add and name the Script component

Add the Python 3 Script component from the Script panel in Grasshopper’s Maths tab. Alternatively, place the general Script component and select Python 3 from its language menu. Double-click the component to open the script editor; the status bar shows which Python language version is in use.

Scripts are usually embedded in the component rather than saved as separate files. If a definition contains multiple scripts, rename each component with a descriptive name. The Script tab and breakpoints panel reflect that name. Give input and output parameters meaningful names too, so anyone inheriting the definition can more easily understand what data it expects and produces.

2. Set up a first script with inputs and outputs

By default, the Script component includes x and y inputs and out and a outputs. Remove any parameters you don’t need. Controls for adding or removing inputs and outputs appear when you zoom in close enough to the component. You can also remove all parameters from one side; the component will display that edge differently.

For a simple first test, add two numbers and assign the result to the a output:

a = x + y

In Script-Mode, the component defines the input variables before the script runs, then passes values assigned to output variables to the component’s outputs. For this example, connect compatible values to the x and y inputs. If the inputs are empty, their values may be None, and adding them will cause a runtime error. Because Python is not a type-safe language, incompatible operations can cause problems when the script runs.

3. Choose input types and data access

Setting a Type Hint by right-clicking an input parameter converts incoming data before the script runs. In the documentation’s example, two Line values are converted to numeric values using the float type hint, and the script adds them. Type Hint options are available for both input and output parameters. Check the connected data to confirm that the conversion produces the expected result.

Parameter Access in the parameter menu determines the scope at which the script handles data:

With Item access, a number appears as a single value on the Python side; with List access, the values in a branch appear as a list. Tree access provides access to the Grasshopper data tree. A type hint can also help specify the element type in a generic DataTree structure. Before choosing an access mode, decide whether the script will handle a single item, a list, or the entire tree.

4. Manage outputs and input requirements

The out parameter captures text produced by print() calls in the script. By default, each line becomes a separate output item. When Avoid Grafting Output Lines is enabled, printed lines are passed as a single item. If the script doesn’t print anything to the console, you can disable the out parameter using the component’s Standard Output/Error Parameter context-menu option.

Disabling an unused out parameter prevents the component from capturing and processing printed text. The documentation notes that the benefit may be small for a single component, but the change can matter more in large Grasshopper definitions where many components run thousands of times.

Script inputs are optional by default. If an input must always have data, use the Required option in the input parameter’s right-click menu. The official documentation says this option has been available since Rhino 8.14. Marking required inputs, especially before publishing a script, helps reduce the risk of running it with missing data.

Use in architecture and visualization workflows

For architects, interior designers, and visualization teams, these settings help turn repetitive modeling steps into a clearer Grasshopper definition. For example, identifying expected data through parameter names and specifying the input type makes it easier to hand a definition over to someone else on the team. Choosing Item, List, or Tree also determines whether the operation applies to individual items or a group of data.

This guide alone isn’t enough for more complex geometry: the source doesn’t cover the Rhino or Grasshopper APIs and directs readers to separate documentation for those topics. So first validate the workflow with a simple script and a small dataset, then move on to the production definition. Since these sources don’t provide information about workstation or licensing requirements, no additional hardware or cost recommendations are offered here.

Common mistakes

• Overlooking empty inputs and operating on None values: check that inputs are connected and have the expected type.

• Choosing parameter access without considering the script’s data requirements: Item, List, and Tree provide different data structures.

• Leaving the unused out parameter enabled: disable it if print() output isn’t needed.

• Using unclear parameter names: this makes the purpose of inputs and outputs harder to understand, especially in shared definitions.