MacOS ModuleNotFoundError

[twigley]

Describe the bug

When running a basic example application python returns the error:

ModuleNotFoundError: No module named 'textual.app'; 'textual' is not a package

To Reproduce

Using a very bare bones app main.py:

from textual.app import App

class MyApp(App):
    pass

if __name__ == "__main__":
    app = MyApp()
    app.run()

Run

pip install textual textual-dev
python main.py

Expected behavior

Should see a blank screen of the textual app

Diagnose:

Textual Diagnostics

Versions

Name	Value
Textual	0.85.2
Rich	13.9.4

Python

Name	Value
Version	3.12.7
Implementation	CPython
Compiler	Clang 16.0.0 (clang-1600.0.26.3)
Executable	/Users/me/git_repos/tmp/pam/.venv/bin/python

Operating System

Name	Value
System	Darwin
Release	23.6.0
Version	Darwin Kernel Version 23.6.0: Wed Jul 31 20:48:04 PDT 2024; root:xnu-10063.141.1.700.5~1/RELEASE_ARM64_T6030

Terminal

Name	Value
Terminal Application	vscode (1.92.2)
TERM	xterm-256color
COLORTERM	truecolor
FORCE_COLOR	Not set
NO_COLOR	Not set

Rich Console options

Name	Value
size	width=161, height=36
legacy_windows	False
min_width	1
max_width	161
is_terminal	True
encoding	utf-8
max_height	36
justify	None
overflow	None
no_wrap	False
highlight	None
markup	None
height	None

Additional context

It seems this might be a Mac/OSX issue. I can run python in docker locally and perform the same steps with the expected result and no error.
I've tried a few Python versions from 3.8, 3.9, 3.12, 3.13 via a venv and get the same result.

pip list shows the package installed in all instances.

[github-actions]

Thank you for your issue. Give us a little time to review it.

PS. You might want to check the FAQ if you haven't done so already.

This is an automated reply, generated by FAQtory

[willmcgugan]

The error indicates that textual isn't installed in the environment you think it is.

This can happen if your pip command was installed with a different version of Python.

I quick solution to this is to use python -m pip rather than pip.

A better solution would be to use virtual environments. Consider using uv which supports "venvs" natively.

[willmcgugan]

This article may also help https://www.bitecode.dev/p/back-to-basics-with-pip-and-venv

[twigley]

Hi @willmcgugan and thanks. I've tried a few different ways both with a venv, just using system level packages and using uv as well.

This is the output from trying the above showing the venv in use and it telling me textual is installed but then still erroring.

❯ cat textual.py  
from textual.app import App

class MyApp(App):
    pass


if __name__ == "__main__":
    app = MyApp()
    app.run()%  

❯ python -m pip install textual
Requirement already satisfied: textual in ./.venv/lib/python3.12/site-packages (0.85.2)
Requirement already satisfied: markdown-it-py>=2.1.0 in ./.venv/lib/python3.12/site-packages (from markdown-it-py[linkify,plugins]>=2.1.0->textual) (3.0.0)
Requirement already satisfied: platformdirs<5,>=3.6.0 in ./.venv/lib/python3.12/site-packages (from textual) (4.3.6)
Requirement already satisfied: rich>=13.3.3 in ./.venv/lib/python3.12/site-packages (from textual) (13.9.4)
Requirement already satisfied: typing-extensions<5.0.0,>=4.4.0 in ./.venv/lib/python3.12/site-packages (from textual) (4.12.2)
Requirement already satisfied: mdurl~=0.1 in ./.venv/lib/python3.12/site-packages (from markdown-it-py>=2.1.0->markdown-it-py[linkify,plugins]>=2.1.0->textual) (0.1.2)
Requirement already satisfied: linkify-it-py<3,>=1 in ./.venv/lib/python3.12/site-packages (from markdown-it-py[linkify,plugins]>=2.1.0->textual) (2.0.3)
Requirement already satisfied: mdit-py-plugins in ./.venv/lib/python3.12/site-packages (from markdown-it-py[linkify,plugins]>=2.1.0->textual) (0.4.2)
Requirement already satisfied: pygments<3.0.0,>=2.13.0 in ./.venv/lib/python3.12/site-packages (from rich>=13.3.3->textual) (2.18.0)
Requirement already satisfied: uc-micro-py in ./.venv/lib/python3.12/site-packages (from linkify-it-py<3,>=1->markdown-it-py[linkify,plugins]>=2.1.0->textual) (1.0.3)


❯ pip list | grep text
google-cloud-access-context-manager 0.2.1
textual                             0.85.2
textual-dev                         1.6.1
textual-serve                       1.1.1

❯ python textual.py
Traceback (most recent call last):
  File "/Users/me/git_repos/tmp/tmp/textual.py", line 1, in <module>
    from textual.app import App
  File "/Users/me/git_repos/tmp/tmp/textual.py", line 1, in <module>
    from textual.app import App
ModuleNotFoundError: No module named 'textual.app'; 'textual' is not a package

❯ python --version
Python 3.12.7

It's very odd. I've only ever come across this error like you say when it's pretty obvious you've not installed the package.

[willmcgugan]

You will need to name your script something other than "textual.py". So that it doesn't clash with the library.

[twigley]

Oh dammit 🥲

Wood for the trees and all that. I've been staring at this for too long and didn't even think about the filename...

Thanks @willmcgugan that's working now 🥇

[github-actions]

Don't forget to star the repository!

Follow @textualizeio for Textual updates.