Isn’t your example just the builder pattern?

I like your explanation, that makes a lot of sense

Or for those using Java: Stream<T> is a monad

I’m not good at this but that’s never stopped me from making a fool of myself before.

Iterators are monads because they have a flatMap on them. It takes each element and spits out a new iterator which is merged in to the result.

Option is a monad too. Same reason. You can map the contents to another option. And you won’t get called if there’s nothing inside.

Promises are monads too. You can map the result to another promise. The wrinkle here is that you don’t get to know when the map happen. Or it might not get called at all if the promise errors out.

IO can be a monad because you can ask it for input and wait for the result. It’s just the same as a promise.

See how these different things share a common behavior? That’s monad. Or, maybe it’s monoid. Names are hard and I’m busy making a fool of myself.

Monads are nothing more than a useful abstraction. Haskell is famous for them because they couldn’t make Haskell do imperative stuff without them so they spread them all over the language.

We all use them every day in regular programming. We just don’t think of them as a class of thing.

This is probably the best explanation I’ve seen:

http://adit.io/posts/2013-04-17-functors,_applicatives,_and_monads_in_pictures.html

I’ll assume you know Python, just so that we can speak the same programming language. (Also, this will make type theorists and category theorists cringe. I know what I’m describing is not generic enough, but it gets the point across)

A Monad is any type which “contains” values of arbitrary other types (think: list, set, etc) - let’s call it the “container” type -, and for which it makes sense to define two operations: unit (you might see it called return in other places but this is very confusing, ignore it) and bind (a.k.a >>= operator).

unit is really easy. It just takes a value of the contained type and returns our container type with that value inside it. E.g. for a list, unit(1) == [1], unit("a") == ["a"]. Here is how we might define unit for a list:

def unit(a):
    return [a]

bind is a bit more complicated, but stick with me. bind takes two arguments. The first argument is a value of our container type, and the second argument is a function which takes the contained value and returns a container (it can have a different contained type, but must have the same container type). Note that we can pass any function we like to bind as the second argument, as long as the types are right.

For example, here is how we might define bind for a list:

def bind(lst, fun):
    new_lst = []
    for element in lst:
        new_lst.extend(fun(element))

    return new_lst

This definition applies the function to every element in the provided list, and returns the list with all the returned elements concatenated.

This definitely sounds weird for a list, but it does make sense in a particular context: describing computations which can produce multiple results.

Let’s say we have two functions, one plus_or_minus(a) = ±a:

def plus_or_minus(a):
    return [a, -a]

And another, double_or_halve(a) = a * 2^(±1):

def double_or_halve(a):
    return [a * 2, a / 2]

Then we can apply them in sequence, using unit to create our starting list, and bind to apply the functions:

bind(
    bind(
        unit(1),
        plus_or_minus
    ),
    double_or_halve
)

What we get in the end is a “flat” list: [2, 0.5, -2, -0.5], listing all possible outcomes of our computations. This can even be slightly useful in some scientific settings.

If this all sounds esoteric, don’t worry, for a list in Python it kind of is! However, some languages like Haskell provide a convenient syntax sugar for monads, which allow you to write monadic expressions as though you are writing imperative code, like this:

do
  a <- pure 1
  b <- plus_or_minus a
  double_or_halve b

And convenient operators, to write concise code like this:

pure 1 >>= plus_or_minus >>= double_or_halve

(Haskell standard library actually provides us with a definition of Monad, and its implementation for a List, such that both these examples are equivalent to the python one)

Hopefully you can start to see that with tooling like this, even a List monad can be occasionally useful.

But the main benefit of Monads comes when you start defining them for other types from the algebraic type land. Take for example Maybe - haskell’s equivalent of Python’s deprecated Optional, or Rust’s Option. It is a type that can either contain a value or nothing at all. In python speak, it is

Union[a, None]

It is also a monad, quite trivially so.

Here’s unit for this type:

def unit(a):
    return a

And here’s bind:

def bind(opt, fun):
    if opt is None:
        return None
    else:
        return fun(opt)

With this monad we can combine “fallible” computations, i.e. computations that can fail for some inputs.

Take for example this:

def reciprocal(a):
    if a == 0:
        return None
    else:
        return 1 / a

This “fails” when the input is zero.

def minus_one(a):
     return a - 1

This function never fails.

We can combine multiple operations like this, guaranteeing that they never get None as an input:

bind(
    bind(
        bind(
            unit(1),
            minus_one
        ),
        reciprocal
    ),
    minus_one
)

(this returns None, but it never calls minus_one(None))

Or like this:

bind(
    bind(
        bind(
            unit(0.5),
            reciprocal
        ),
        minus_one
    ),
    minus_one
)

(this returns 0)

Once again this is much more elegant in Haskell: pure 1 >>= minus_one >>= reciprocal >>= minus_one or pure 0.5 >>= reciprocal >>= minus_one >>= minus_one

Notice how the structure of bind and unit calls is the same for both the list and the optional. This allows us to write functions which operate on arbitrary monads, which makes them useful for hundreds of seemingly very different types; it also allows Haskell to make syntax sugar which makes code more readable and understandable across dozens of different domains. It unifies a lot of different concepts into one “API”, making it much easier to write generic code that encapsulates all those concepts.

Just as a glimpse of how powerful this is, a typical project structure in Haskell is to define your entire application domain (serving web pages, querying an SQL server, writing data to files) as a single monadic type; explaining this takes a lot more time, effort, and monad transformers.

However, the most useful part of Monads in Haskell is difficult to describe in Python. It is the fact that Monads perfectly encapsulate the “side effects” of a program, i.e. how it interacts with the real world around us (as opposed to side-effect-less computations). Haskell actually defines all side effects as functions which take and return the entirety of the “real world” (sounds insane, but it’s actually really elegant); think something like this (python syntax):

def print(a: RealWorld, string: str) -> RealWorld: # <...>

And the side effect is then thought of as the difference between the RealWorld the function takes as argument and returns.

In order to take values from the real world (think: read the value from stdin, a-la python’s input), Haskell then defines an IO type, which “contains” some value a which was “taken” from the real world. The details are deliberately hidden from the programmer here, so that you can’t just “unwrap” the IO value and take the “contained” value from it from your side-effect-less function; you have to be inside the IO monad to do anything with the value. Under the hood it is defined as something like this (python syntax):

type IO[a] = Callable[RealWorld, (RealWorld, a)]

(don’t dwell too much on the details here, it is admittedly confusing)

So, print is actually defined closer to this:

def print(string: str) -> IO[]:

(which can be read as: take a string and return some action in the real world, which doesn’t return anything)

And getLine (Haskell’s analog of python’s input) is defined something like this:

def getLine() -> IO [str]:

(which reads: return some action in the real world, which returns a string)

This means that you can technically “call” both print and getLine from side-effect-less code, but they will simply give you an opaque value of type IO, which you can’t do anything outside the IO monad. So that you can do anything with this type, the main function in Haskell is defined something like this:

def main() -> IO[]:

This then allows you to combine getLine and print as follows:

def main() -> IO[]:
    return bind(getLine(), print)

This reads one line from stdin and prints it to stdout.

The actual Haskell function looks like this:

main = getLine >>= print

Neither the getLine nor the print calls actually executed any code that read or printed anything; that code was executed by some mysterious “runtime” which first called the main function, got an IO () operation from it, and then executed that operation in its entirety.

This is probably very confusing; worry not, it will be, we’re trying to do this in Python! I swear it makes much more sense in the context of Haskell. I highly recommend reading https://learnyouahaskell.com/chapters to learn more.

As fun exercises to make sure you understand monads, think of the following:

• Can you come up with a (generic) type which isn’t a monad?
• Are functions monads? (hint: the answer is contained in this comment)
• Is it possible for a type to be a monad in multiple different ways? Think of examples.

http://blog.sigfpe.com/2006/08/you-could-have-invented-monads-and.html

It’s a “programmable semicolon” or “decorated-function composition”. I think most people that are confused about it, are trying to make it be more meaningful than it is. Haskell (?) just grabbed a math name so they’d have one word for it, because it’s a useful class name there.

I switched to the simple English Wikipedia article:

https://simple.wikipedia.org/wiki/Monad_(functional_programming)

Monad is (a classes of type of) a collapsible container. Collapsible, like how you can flatten a nested list, or Option<Option<A>> can be flattened to Option<A>.

A common pattern with monads is the flatMap function, where you apply function A -> List<B> to (each element of) List<A> to obtain List<B>. This happen to represent erroneous call chaining with Option or Result types.

I liked this explanation:

https://alexyorke.github.io/2025/06/29/list-is-a-monad/

It’s like a burrito

They’re just an abstraction to model and contain implicits, for instance like IO (filesystems) or program state. Regular functions should produce the same output for the same input, if they do not you have implicit effects. You can think of it kinda like a class, or a context, or a module which has some functions to help work with the implicit effect. Central then is also that each such class, context, or module can be composed with others of the same kind, maintaining a lineage of the implicit effect.