Scope for-loop iterator variables to their loop context

[richbai90]

Suggestion: Scope for-loop iterator variables to their loop context

Problem

for item in collection:
    # do stuff

This pattern is one of the most common constructs in Python programming. Typically, the item variable is intended to be temporary and only meaningful within the loop's context. However, in Python, this variable persists in the namespace after the loop completes.

In marimo, this behavior creates unexpected issues when the same iterator variable name is reused across different cells:

Proposed Solution

I suggest that marimo treats for-loop iterator variables as scoped to their loop context by default. This would better align with the programmer's intent, where these variables are typically meant to be temporary.

Current Workarounds

Currently, users must:

• Use private variable naming conventions like _item to indicate temporary status
• Be careful to use unique iterator variable names across all cells
• Explicitly delete variables after use

Benefits

• Reduces unexpected variable collisions between cells
• Better matches programmer intent for iterator variables
• Maintains compatibility with standard Python while improving the notebook experience

Implementation Considerations

This could be implemented as:

• A default behavior with an option to disable
• An opt-in feature via configuration

Would love to hear your thoughts on this suggestion!

[dmadisetti]

Maintains compatibility with standard Python while improving the notebook experience

This is not true, keeping the last variable in scope is standard python. Maybe keeping it in scope within just the cell makes sense- but maybe frustrating if you did want the correct behavior.

But this is a common complaint.

what about implicitly private variables being declared:

# suggested as import because it's easiest to hook into the ast
from marimo.private import i, j, k, dynamic_name
# reuse i as much as you want across cells

---

Another suggestion (harder to implement, and less elegant)

from marimo import range, enumerate, zip

Where the imported behavior is what you proposed? (Users could also do mo.range as well)

---

Here are some other suggestions that have been mentioned before:

• just make the auto-fix buttons better (auto rename to _i)
• treat single character variables in a special way. But this once again has issues if it's not what you expect.

[dmadisetti]

marimo.locals might make more sense

[richbai90]

I'm not sure if I like the dynamic imports. What about something like this?

import marimo as mo
let i, j, k = mo.locals()
# use i, j, k wherever you like 

The AST can infer how many variables that mo.locals() should return.

[dmadisetti]

Also the with option is not exclusive with the other 2. But assignment and import should probably be exclusive

[richbai90]

While the proposed solution of from mo.locals import i, j, foo, bar could work for iterator variables, I have significant concerns with this approach:

Issues with Import Syntax

1. Unexpected Mental Model

from mo.locals import i, j, foo, bar, whatever
for i in range(10):
    # ...

This syntax is fundamentally confusing. If I encountered this code without prior knowledge, I'd be perplexed about why values are being imported and then immediately reassigned. It creates a mental disconnect between the expected behavior of imports (bringing in existing functionality) and what's actually happening (declaring local variables).

2. Disrupts Programming Flow

Having to declare variables ahead of time breaks the natural flow of programming:

• I'd need to anticipate all local variables before writing my code
• If I realize mid-development that I need another local variable, I'd have to interrupt my flow to go modify the import statement
• It adds cognitive overhead to the development process

Proposed Alternative: Context Manager Approach

Instead, I find the context manager approach to be much more intuitive:

# In the initial setup cell
from marimo import local_scope

# Later, in any cell where local scope is needed
with local_scope:
    # Everything declared here is local to this scope
    for i in range(10):
        # i is local
    # Other local variables as needed

Benefits of the Context Manager Approach:

1. Clarity: The scope boundaries are visually clear
2. Flexibility: No need to predeclare variable names
3. Intuitive: Follows Python's established pattern for managing context
4. Scalable: Works for any scenario requiring local scope, not just loops

Summary

While the import syntax might solve the specific issue of iterator variables in loops, the context manager approach provides a more comprehensive, intuitive, and flexible solution for managing scope in Marimo notebooks. It allows for a more natural programming experience without forcing users to predefine their variable names or interrupt their workflow.

[dmadisetti]

I agree that redefining variables is counter intuitive- I also agree local_scope makes sense. However, it still provides some overhead, and doesn't offer much more than what is already done with the wrap in a function button:

I'm not sure the added complexity is worth it for a marginal solution

---

A declarative approach could be:

# Only allowed in the setup cell
marimo.declare_local("i", "j", "k", "ax", "fig") # mo.declare_local("i,j,k,ax,fig")

or even on the app level:

App(locals=["i", "j", "k", "ax", "fig"])

I'm partial to the first case, because it is declared in code (So immediately obvious to the user, where as App parameters are usually a bit more hidden in the editor interface). Both cases can actually can be implemented without any additional static analysis.

• ✅ pure python
• ✅ statically detectable by heuristic (but not needed for implementation)
• ✅ obvious, explicit

A downside is that the local declarations could be obscured, in a way that's not possible in the other options:

my_locals = ["i", "j", "k", "ax", "fig"]
if condition:
    my_locals.pop(1)
marimo.declare_local(my_locals)

But we could do a bit of analysis to throw an error

---

Regarding the concerns:

I'd need to anticipate all local variables before writing my code

If I realize mid-development that I need another local variable, I'd have to interrupt my flow to go modify the import statement

I think a quick fix-button (like above) can address this pretty easily. I think it can also be implemented in a way that doesn't require a full notebook rerun (like we do with import cells). A benefit of the import approach is that this is done for free.

It adds cognitive overhead to the development process

Agreed in that I think the feature could be abused in such a way that a notebook becomes confusing.
However, there's the proposal for marimo lint, that would provide best practices suggestions specific to marimo: #1543
I think that these are reasonable lint rules:

• limit variables to 3 characters: motivation; prefer the _ prefix, and restrict local variables to common shorthand temp variables used in typical python (fig, ax, i, j, x, y, etc..)
• more than 1 reference: motivation; if you only use the variable once (or not at all), then it should not be declared local.

But aside from that, I think it's set it and leave it. I would argue it's more cognitive load to remember what the variable i contains, or ax if you are using declare_local reasonably.

[dylanbay11]

I definitely wouldn't consider myself an expert, but from a user perspective, I like the declarative idea and would love something like that.

At risk of belaboring the more general point, currently I think marimo's philosophy often 'nudges' users toward "good python" by avoiding variable re-use. However, in this case marimo runs counter to some very deep-seated habits: consider how for i in collection and for k, v in dict.items() are taught as if they were locally defined and ephemeral, even if this is not technically true. Usually that's fine! When was the last time you met a python programmer that didn't avoid using i as a global variable or reserved keyword?

A simple declaration at the top is pretty painless. In terms of philosophy (simple, immersive, interactive, seamless, and fun) I think especially with a quick-fix button, perhaps triggering only on a shortlist of common names, it would be far superior to the current state of affairs, which violates almost all of them as collateral damage. While universal declarations at the top isn't typically pythonic, it is instantly readable and low-friction and enables far more-pythonic behavior, especially for beginners and boilerplate-pasters who are accustomed to those variables being effectively local.

[akshayka]

I appreciate the thoughtful comments. But unfortunately none of these suggestions are something we can adapt. They provide a small amount of convenience, but sacrifice consistency and simplicity. They also increase marimo's learning curve rather than flattening it, adding yet another thing to learn.

Again I appreciate the enthusiasm, but we won't change our position on this. I am making this statement definitely to preclude further discussion.

[PetterS]

I still think that just allowing variables that are first written to (not read) in all cells where they appear would be nice and safe. #1477

[richbai90]

Honestly, I'd take this a step further. Maintain some type of dependency graph and each time a variable is defined/redefined is a root node. This solves the problem you posed because cell 2 would be dependent on cell 1 but cell 3 would be a root node.

Here's an example:

Cell 1: df write before read
Cell 2: df write before read
Cell 3: df read before write, new_df write before read
Cell 4: df read before write
Cell 5: df write before read
Cell 6: df read before write
Cell 7: new_df read before write
Cell 8: new_df write before read

The resulting dependency graph would look something like this

flowchart TD
    A[c1: df = ...] 
    B["c2: df = expensive_calc()"]
    C[c3: new_df = df + ...]
    D["c4: df[col_1] = ..."]
    E[c5: df = ...]
    F["c6: df[col_2] = ..."]
    G[c7: new_df += ...]
    H[c8: new_df = ...]
    B--->D
    B--->C
    E--->F
    C--->G

Loading

I'm not sure how this would work in the context of the Marimo internals and it may be too lenient for some. In this case I think it's a question of which behavior is more burdensome, the current behavior or the potential pit-fall. Given that the noted pit-fall is more of an edge case, I think the proposal in #1477 make a lot of sense.

[dmadisetti]

Just because we'd track state doesn't mean it doesn't make it less confusing, or create the same issues we've been trying to solve (you might just be more aware with the right UX, but it's still not good practice). There's also the issue of associating the correct df with the right graph, when you can just do this with a new name.

Mutation operations are also basically impossible to trace since there's FFI, local packages, and a million other things to potentially support.

---

A bit opinionated but: the policy of no repeated variables is the best and correct one

However, I do think it's worth exploring how to loosen the policy a little since temp variables like df, ax and fig are so idiomatic to python.

So, not trying to solve the reassignment issue, just the "I don't want to prefix everything with _" issue

[richbai90]

If tackling the reassignment issue is a non start, I'm not sure there's a more intuitive way than the undscore prefix. Maybe it's just something developers will have to adapt to in order to get the niceness that marimo provides.

[PetterS]

I think that solution works well for cases when you don't want to read the variable,

Yes, that is the only case it should solve.

[PetterS]

I think the benefits outweight the downsides. Not being able to have a simple for loop in more than one cell is a pretty big downside. And the plotting mentioned in #1477 is also very common

[jameskermode]

+1 from a lecture notebook author, with a concrete use case that may help frame the trade-off.

I'm exploring using marimo to deliver postgraduate lectures with 60–100 cells per notebook, mostly plotting/demo cells that compute intermediate values just to render a figure. None of those intermediates need to escape the cell, and I'm bulk converting from exisitng Jupyter, so I am prefixing everything with _ (admittedly over-zealously). A typical cell looks like:

app.cell(hide_code=True)
def _(np, plt, cp):
   _dist = cp.Normal(0, 1)
   _expansion = cp.generate_expansion(3, _dist, normed=True)
   _x = np.linspace(-3, 3, 200)
   _phi_x = _expansion(_x).T
   _fig, (_ax1, _ax2) = plt.subplots(1, 2)
   _ax1.plot(_x, _phi_x)
   # ... 15 more lines, every variable prefixed ...
   _fig
   return

@dmadisetti's point that a context manager doesn't add much over the "wrap in a function" autofix is fair for short cells. For the long demo cells I have, the function-wrapping pattern (def _impl(): ... ; _impl()) introduces an extra indentation level and a call site that's its own form of clutter, but I take the point that it's already supported. I appreciate the openness to loosening for idiomatic temp variables (df, ax, fig) without requiring underscore prefixes, and this is the direction I'd most like to see explored. For notebook authors, the noisy variables in lecture/demo cells are almost always exactly that small set: fig, ax, axs, x, y, df, cmap, etc.

To me the declarative alternative (marimo.declare_local("i", "j", "k", "ax", "fig") in a setup cell) feels less ergonomic than it sounds in practice. In a 100-cell lecture notebook, the set of "cell-local" variables varies cell-by-cell: one cell has _fig, _ax1, _ax2, the next has _im, _cb, the next has _t, _samples, _kde. A single declared list would either need to include the union of all these (becoming a wall of names in the setup cell, and offering no spatial cue at the point of use), or be redeclared per cell, at which point it's just the underscore convention written more verbosely.

The strongest argument I'd add for some form of explicit-locality marker (whatever the syntax) is that the friction isn't really about typing the underscores. It's about the cognitive load when reviewing or modifying a cell: in the example above, almost every variable name has a sigil that has to be visually filtered out. For lecture material that's read by students and reviewed by colleagues who aren't marimo-fluent, this is the biggest cost.

If the team's preferred direction is the idiomatic-name allowlist, that would solve 90% of my use case with zero new syntax: fig, ax, axs, axes would just stop counting as global definitions. I'd happily contribute a default list of plotting-related names if that helps move things forward.

[akshayka]

The team's preference is not an allowlist. See my comment on @dmadisetti's proposal. We can't support it.

When you find yourself reaching for locals, you should instead encapsulate code in a function with a meaningful name. I do this again and again in my own notebooks.

[daizutabi]

@akshayka I understand the team's position on the allowlist, and I respect that decision.

That said, the pain point remains for users migrating from Jupyter Notebook. In Jupyter, writing fig, ax = plt.subplots() across multiple cells is the most natural and common pattern. Being forced to use _ prefixes or function wrappers in marimo adds friction to migration.

I've proposed a different approach - Sink cells (#9122) - that eliminates this friction while preserving the integrity of the DAG. Marimo already has setup cells, which serve as the source of the DAG. Sink cells are the natural counterpart. Users should have the ability to explicitly define the boundaries of their DAG - both the source and the sink.

[jameskermode]

Understood, thanks @akshayka for clarifying. I'll try to use more functions, but they do feel a bit heavy for 5-10 lines of code to setup a plot. Probably just a mental shift required. I'll be able to report back how students find this...

[stuglaser]

I also need to wrap many cells in private functions, or my notebooks turn into underscore soup. Since I do a lot of plotting, most cells have this extra boilerplate.

I'm hoping the marimo team will reconsider this decision at some point. Right now my marimo notebooks feel kludgy and unreadable, and I don't enjoy returning to them to make edits.

[joewalp]

Perhaps it would suffice for Marimo to honor the del statement, as in:

@app.cell
def _():
    x = 0
    del x
    return

@app.cell
def _():
    x = 0
    return (x,)

@app.cell
def _(x):
    x
    return

[joewalp]

I have framed the del statement workaround proposal as bug #9347.

[dmadisetti]

Thanks for commenting on this issue. Definite addition to the conversation for others to follow. I'm going to close out your ticket, since I'm not sure there's anything actionable at this point and we're not likely to change control flow primitives.

Context for other readers del could be used to indicate a temporary variable.