Nicegui storage - frustration

[phifuh]

I am very curious whether other people have trouble understanding the docs at https://nicegui.io/documentation/storage. It’s my fifth time reading them and I still have absolutely no clue what they mean or how to use the feature. I’m so frustrated right now that this might sound like a rant. Asking my friend “Claude” yields wildly different explanations, and I don’t understand how it works. What does “needs client connection” mean? How does the storage work in native mode? Is data only synchronized when the app explicitly performs the heavy lifting, like implementing it, or implementing it on startup? What happens if I run my app on localhost? How can I kill the connection to prevent multiple tabs from staying open in localhost mode? I have so many unanswered questions and I’m just angry.

[phifuh]

• what is a non-duplicated tab sessions?
• If i use the tab storage, it says "accros server restarts yes" in the table below, but in the text above its says its not yet implemented?

[phifuh]

I think one of the issues is that we run the app via Citrix on a local shared drive, so technically we run a local server instance and not a web server; consequently, the storage becomes more confusing. We tried running the native mode, but I suspect it didn’t work because the default port was taken if a second user opens the app. To handle this, maybe we could implement a port scanner, then run native mode and have fewer storage headaches? I don’t know—I’m just dropping my current thoughts in a non‑ordered fashion.

[evnchn]

Hello @phifuh

Braindump is fine but someone has to gather it together. I think that someone is best be LLM. Here I asked Claude to do it. If you have access, maybe you can have LLM help you as well, to ease your frustration also.

Braindump organized, but accuracy unknown

Concerns from Discussion #5717

Overview

User experiencing significant confusion with NiceGUI's storage feature documentation and implementation guidance.

Primary Concerns

1. Documentation Clarity Issues

• User read storage documentation "five times" but still unclear on usage
• Documentation lacks clear, practical examples
• Inconsistencies between different sections of docs:
  • Table shows tab storage as "across server restarts: yes"
  • Text describes it as "not yet implemented"

2. Technical Confusion Points

• "Needs client connection" terminology is unclear
• Storage behavior in native mode is not well-documented
• Data synchronization mechanics are confusing:
  • When/how does initialization happen?
  • How does multi-tab session handling work?
• Localhost behavior is uncertain

3. Non-Standard Deployment Scenario

• Application runs via Citrix on a local shared drive
• Not a traditional web server deployment
• Port conflicts when multiple users access simultaneously
• Each instance needs different port in native mode
• Unclear how storage works in this environment

4. Suggested Improvement

• Implement automatic port scanner to handle conflicts
• Would simplify multi-instance native mode deployments
• Help avoid manual port management in shared environments

Root Issue

Documentation assumes standard web deployment. Non-traditional deployments (Citrix, shared drives, multi-user native mode) lack clear guidance and examples.

---

Documentation fix is under way

As I always say, it is our fault if our users do not understand any line of our documentation. I have took action and began to modify the documentation with more content which should hopefully help to make this happen never again, and I shall address my changes in that PR. Feel free to have a read once it's ready, we always welcome a third pair of eyes 👀

---

With that, I want to cut to the chase. While information is sparse, based on your description of running via Citrix on a local shared drive, I think I have a guess of what is happening with why NiceGUI isn't working in your setup.

TL-DR: Storage conflict. Dodge the storage conflict and it should work. If it doesn't please report back and let's debug together!

Non-issue: Port Conflict

Native mode already has automatic port scanning built in. When you run ui.run(native=True) without specifying a port, NiceGUI automatically tries to find an available port:

nicegui/nicegui/ui_run.py

Line 238 in fce74fc

port = port or native_module.find_open_port()

nicegui/nicegui/native/native_mode.py

Line 127 in fce74fc

def find_open_port(start_port: int = 8000, end_port: int = 8999) -> int:

As it scans ports 8000-8999 to find an available one, likely multiple users can run the app simultaneously without port conflicts.

Suspected issue: Storage

Under your case, it seems like the same file (main.py, or main.exe if you packed into PyInstaller) may be run multiple times, despite it is the same file.

When that happens, all of such instances attempt to write to the same storage path (defaults to .nicegui in the working directory, can be configured via NICEGUI_STORAGE_PATH).

This causes conflicts and possibly data corruption, and is likely what is going wrong.

Solutions

Option 1: Separate Storage Paths

Each user needs their own storage directory. You can set this via environment variable before running the app:

# Windows, since I recall you are Windows user (?)
set NICEGUI_STORAGE_PATH=C:\Users\%USERNAME%\.nicegui_myapp
python your_app.py

This way each user gets their own isolated storage, preventing conflicts.

Option 2: Redis Storage

If you actually want users to share data, you can use Redis storage instead:

set NICEGUI_REDIS_URL=YOUR_REDIS_SERVER
python your_app.py

This requires setting up a Redis server but allows proper multi-instance data sharing with synchronization.

[evnchn]

#5719

[phifuh]

Hey @evnchn,

Thanks for taking the time to read the braindump and rant, and for digging even deeper. I really appreciate it. I am using Claude, github copilot, local olama and lumo but in this case i just vented my thoughts, so sorry for that.

Regarding the port issue, you mentioned “native mode,” but we’re running in browser mode on localhost, where multiple users can start a new instance. Does the port scanner automatically try to find an open port even non naitive?

The information about the storage path on Windows was very helpful—thanks for that.

I’ll read the PR and give feedback soon.