Dynamo: the complete guide to visual programming for Revit — what it is, what it does, Dynamo vs the Revit API, and how to learn it

Dynamo is the visual programming tool that ships with Revit. Instead of writing code, you drag blocks called nodes and join them with wires into a diagram. Revit then does what the diagram says. A job you would repeat by hand hundreds of times, Dynamo does in seconds. Its full name is Dynamo BIM or Dynamo for Revit, not to be confused with the electrical dynamo.

This is the Institute of Information Technology in Civil Engineering's overview page on Dynamo. Dynamo is introduced in the Institute's Revit courses and in its Robot Structural Analysis course, and taught in more depth when a company books an in-house class. The page answers the questions our students ask most: what Dynamo is, whether it needs a separate install, what is inside a graph, what engineers use it for, how it differs from the Revit API, and how long it takes to learn.

What Dynamo is

Dynamo is a visual programming language. "Visual" means you see the program as a diagram. Each block in the diagram is a node that does one small job: select every door in the model, read a parameter, read an Excel sheet, add two numbers. The lines between nodes are wires. The whole diagram is a graph. Data flows from the nodes on the left to the nodes on the right, like water through pipes.

Take a familiar example. A building has three hundred rooms. The architect has to number them floor by floor, clockwise. By hand that takes half a day, and a few rooms are almost always missed. Then the layout changes and it has to be done again. With Dynamo, the numbering graph is written once and rerun as often as needed, a few seconds each time.

The picture at the top of this article is one such graph, read from left to right. File Path and Data.ImportExcel open the workbook and take the sheet "Columns". List.GetItemAtIndex pulls out column 2 of the table, the element codes. On the lower branch, All Elements of Category collects every structural column in the model. The last node, Element.SetParameterByName, writes each value into the "Element code" parameter of each column. Nine nodes, not a line of code. When the spreadsheet changes, run it again.

Dynamo was written by the engineer Ian Keough around 2010. He was working at the consultancy Buro Happold and had to move data between Rhino and Revit every day. In 2011 he released the source code. Autodesk later took the project on and has developed it ever since. The code is still open on GitHub under the Apache 2.0 licence, and Dynamo is completely free.

The single most important thing about Dynamo: it does not replace Revit, it drives Revit. To tell Dynamo to do something, you have to know how Revit does it. Someone who does not yet understand families, parameters and categories in Revit is not ready for Dynamo. If you are new, start with Revit: the complete guide or one of the Institute's Revit courses by discipline.

How Dynamo fits with Revit

You meet Dynamo in four places across the Autodesk range.

Dynamo for Revit is the common one. Since Revit 2020, Dynamo has been installed together with Revit. You open it from the Manage tab. Nothing else to download. Earlier Revit releases needed a separate Dynamo install. Each Revit release ships with a particular Dynamo release, and Autodesk updates the two in step. So when someone asks "which Dynamo are you on", the answer is nearly always "which Revit".

Dynamo Player is a small window for running existing graphs. The user picks a graph, fills in a few inputs and presses run. No editor to open, nothing to understand inside. Dynamo Player has been in Revit since 2017.1. This is how most engineers in an office use Dynamo: one person writes the graph, the whole office runs it.

Dynamo Sandbox is the standalone version that runs without Revit. It is for learning geometry and trying graphs on a machine without Revit. It has no Revit nodes.

Dynamo in other software. Civil 3D has had Dynamo since the 2020 release, for alignments, profiles and corridors. Robot Structural Analysis integrates Dynamo with a "Structural Analysis" node set: build the analysis model, assign sections, supports and loads, then read the results back. Advance Steel and FormIt also carry Dynamo. Inside Revit, Generative Design runs on Dynamo graphs to generate and compare many layout options.

What is inside a graph

Learning Dynamo means learning five things. The first four are easy. The fifth is where everyone stumbles.

Nodes live in the library on the left, grouped by purpose. The Revit group has nodes that select elements, read and write parameters, create views and sheets. The Geometry group builds points, curves, surfaces and solids. The List group handles lists. Math and String handle numbers and text. Import reads Excel, CSV and images.

Wires join an output port of one node to an input port of another. Ports have data types. Connect the wrong type and the node turns yellow or red. A Watch node shows the data flowing through any wire.

Code Block is a box where you type instead of dragging nodes. A number, a string, a formula, a range like 0..10. As people gain confidence they use Code Blocks in place of many small nodes, and the graph visibly tidies up.

Python Script is a node that lets you write Python inside Dynamo. When no built-in node does what you need, you write a few lines of Python that call the Revit API directly. This is the bridge from Dynamo to real programming.

A cluster of nodes you use again and again can be wrapped into a custom node: a new node with your own name and its own input and output ports. The graph gets shorter, and colleagues can use the node without understanding what is inside.

Lists are the stumbling block. Revit has three storeys with twenty columns each. Dynamo sees that as a list of three items, each of which is a list of twenty. To name every column, you have to tell the node which level of the list it is working at. Dynamo calls this levels and lacing. Most graphs that "run but give the wrong answer" fail here. Learners should give lists a few dedicated sessions rather than skimming past.

Packages: the community's node libraries

The nodes built into Dynamo are only the core. The community has written thousands more, bundled as packages, and anyone can install them free through the Package Manager inside Dynamo.

A few names you will meet in the first week:

• Clockwork and archi-lab — two general-purpose node sets for Revit that fill most of the gaps in the built-in nodes.
• Rhythm — nodes for views, sheets, tags and other daily tasks.
• Data-Shapes — builds input dialogs, so a graph run through Dynamo Player gets a proper interface.
• Genius Loci — geometry and MEP nodes.
• MEPover — for MEP engineers: ducts, cable trays, systems.
• BimorphNodes — clash detection inside Revit.
• Structural Analysis for Dynamo — by Autodesk, links Dynamo to Robot Structural Analysis.

Packages have a downside. A package written for one Dynamo release may not run on another. Change Revit and a graph can break. Two good habits follow: note in the graph which packages and versions it uses, and prefer built-in nodes whenever they can do the job.

Six everyday tasks engineers hand to Dynamo

From the Institute's Revit classes, these are the six Dynamo tasks students ask about most. Each has a sample graph on the Dynamo forum; adjust a few nodes and it is ready to use.

1. Bulk numbering and naming. Rooms, doors, columns, piles and sheets by the office rule. Change the rule, rerun.
2. Excel into the model, and back. Element codes, levels and equipment data sit in another department's spreadsheet. Dynamo reads the sheet and writes each value into the right element's parameter. In the other direction, Dynamo exports quantities in exactly the office's table template.
3. Placing elements by coordinates. Column grids, piles, anchor bolts and equipment from a survey coordinate table. A few hundred points, a few seconds.
4. Views and sheets in bulk. Eighty column detail sheets, each with the right title block, scale and name. A day's work becomes ten minutes.
5. Model checking. Find elements with no parameter value, rooms with no name, elements on the wrong level, then colour them for the modeller to fix. This is what a BIM manager runs before every issue of the drawings.
6. Complex geometry. Curved facades, shell roofs, louvres rotated to the sun, railings along curves. Things that are nearly impossible to model by hand.

Structural engineers have a seventh: send the model from Revit to Robot for analysis, then read the forces back, all through Dynamo. The Institute's Robot Structural Analysis course introduces this workflow.

Three mistakes beginners make

Most questions on the Dynamo forum come down to three situations.

• The graph runs but the model does not change. Usually the graph is in Manual mode and Run was never pressed, or a node upstream returned null, so the writing node had nothing to write. To trace it, put a Watch node after each node and work backwards from right to left until the data disappears.
• A node turns yellow or shows Unresolved. This machine lacks a package the graph uses, or has the wrong version of it for this Dynamo. Reinstall the right version from the Package Manager. This is why package names and versions belong inside the graph as a note.
• It runs cleanly and the result is wrong. Almost always level or lacing: the right values written to the wrong level of the list. Test on three or four elements before running on the whole model.

One more habit: switch large graphs to Manual mode. In Automatic mode Dynamo re-runs the whole graph every time you touch a node, and a heavy model will freeze.

Dynamo, the Revit API or Grasshopper

These three names are often placed side by side. They solve three different problems.

The Institute's advice has not changed in years. Start with Dynamo. Move to C# when a tool has to run many times or serve many people. The article What is the Revit API? goes into the C# route and how much programming it needs. Grasshopper belongs to architects shaping forms in Rhino; anyone whose main work is in Revit should pick Dynamo.

Learning Dynamo: do you need programming, and how long does it take

You do not need programming to start. You need two other things.

First, a solid grip on Revit. Dynamo only drives Revit. If you do not know which parameter Revit stores a room name in, you cannot tell Dynamo to rename rooms. The people who learn Dynamo well are the ones who have already built a few real models.

Second, a willingness to think in lists. Not "this column" but "every 300×300 column on level three". That habit takes a few weeks to form. Once it has, the rest of Dynamo comes quickly.

The path the Institute's lecturers usually suggest:

• First two weeks: the interface, core nodes, running sample graphs through Dynamo Player, reading Excel into the model. Finish with one graph of your own for a job you currently do by hand.
• The next one to two months: lists, levels, lacing; installing and using packages; graphs for three or four recurring jobs at your office. This is the deciding stretch. Get through lists and you can use Dynamo.
• After that: the Python Script node for what built-in nodes cannot do. When a graph grows past one screen and the whole office runs it, that is the moment to consider C#.

The free resources are good enough: Autodesk's Dynamo Primer goes from the basics to packages, and the Dynamo forum has an answer for nearly every error you will hit. What self-study lacks is someone to point out where your graph is wrong, above all in the list part.

At the Institute of Information Technology in Civil Engineering, Dynamo is introduced in the Revit courses by discipline and in the Robot Structural Analysis course, as the automation part of each course. Those who want to go on to C# have the Revit API programming course. Companies that need a dedicated Dynamo class can book an in-house course, built around the jobs their technical department is still doing by hand.

Frequently asked questions

Is Dynamo free?

Yes. Dynamo ships with Revit at no extra charge, and its source code is open under the Apache 2.0 licence. The separately downloaded Dynamo Sandbox is free too.

Do I need to know programming for Dynamo?

Not to start. You drag nodes and connect wires; you do not write code. Programming only comes in when you want the Python Script node or move on to C#.

How do Dynamo and the Revit API differ?

Both go through the same door: the Revit API. Dynamo goes through it as a diagram, gets results fast and suits individual work. C# goes through it as code, takes more effort, and produces tools an office can use for years. What is the Revit API? has a detailed comparison table.

What is Dynamo Player?

A window for running existing graphs without opening the Dynamo editor. The user picks a graph, fills in the inputs and presses run. Thanks to it, one person writes a graph and the whole office can use it.

Will a graph written on one Revit run on another?

A graph built only from built-in nodes usually will. A graph that uses packages depends on whether those packages have a release for the newer Dynamo. That is why you should note the packages and versions inside the graph.

Does Dynamo work with Civil 3D and Robot?

Yes. Civil 3D has had Dynamo since the 2020 release. Robot Structural Analysis integrates Dynamo with a node set for building the analysis model, assigning loads and reading results.

Related articles

• Revit: the complete guide to Autodesk's BIM software
• What is the Revit API? Can an engineer with no programming background learn it
• What is a family in Revit, and why your library sets your modelling speed
• A learning path for Revit beginners: what to learn first, and how long until you are employable
• In-house Revit and BIM training for companies
• What is BIM? An explanation for people outside the industry