Install Textual in Python Guide

Textual is a powerful Python library for building text-based user interfaces (TUIs). It lets you create interactive, colorful, and responsive apps right inside your terminal. Installing it is simple and fast.

This guide walks you through the installation process step by step. You will learn how to set up Textual on Windows, macOS, and Linux. No previous experience with TUIs is needed.

What is Textual?

Textual is a framework for building terminal applications. It uses widgets, layouts, and event handlers. Think of it like a web framework, but for your command line.

It works with Python 3.8 and above. Textual apps look modern and support mouse input, colors, and animations. Many developers use it for dashboards, log viewers, and interactive tools.

To get started, you need Python installed on your system. If you don't have it, download it from python.org. Then open a terminal or command prompt.

Install Textual with pip

The easiest way to install Textual is using pip. Pip is the standard package manager for Python. Run this command in your terminal:

pip install textual

This command downloads the latest version of Textual and all its dependencies. The process takes only a few seconds. You will see a progress bar and then a success message.

If you use Python 3 on some systems, you might need to use pip3 instead:

pip3 install textual

For users with multiple Python versions, consider using a virtual environment. Virtual environments keep your project dependencies isolated. This prevents conflicts with other packages.

Using a Virtual Environment (Recommended)

First, create a virtual environment. Navigate to your project folder and run:

python -m venv myenv

Activate it. On Windows, use:

myenv\Scripts\activate

On macOS or Linux, use:

source myenv/bin/activate

Now install Textual inside this environment:

pip install textual

Your environment is now ready. All installed packages stay inside this folder. When you are done, deactivate with the deactivate command.

Verify Your Installation

After installation, check if it works. Run this simple Python script:

# test_textual.py
import textual
print("Textual version:", textual.__version__)

Execute the script:

python test_textual.py

You should see output similar to this:

Textual version: 0.52.1

The version number may differ. If you see an error, double-check your Python installation and try again. A successful import means Textual is ready to use.

Run Your First Textual App

Let's create a minimal Textual application. Write this code in a file named app.py:

# app.py - A minimal Textual app
from textual.app import App
from textual.widgets import Label

class HelloApp(App):
    """A simple Textual app with a label."""
    def compose(self):
        yield Label("Hello, Textual!")

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

Run the app:

python app.py

Your terminal will show a clean interface with the text "Hello, Textual!". Press Ctrl+C to exit the app. This confirms your installation works perfectly.

Install Additional Features

Textual offers extra features for development. You can install the development tools to get live reloading and debugging:

pip install "textual[dev]"

This adds tools like textual run and textual keys. The textual run command watches your files and restarts the app on changes. It is very useful during development.

To use the dev tools, run your app with:

textual run app.py

Now edit your app.py file and save. The app restarts automatically. This speeds up your workflow significantly.

Troubleshooting Common Issues

Sometimes installation fails. Here are common problems and solutions.

Permission denied: On Linux or macOS, you may need to use sudo:

sudo pip install textual

Better yet, use a virtual environment to avoid permission issues.

pip not found: If pip is missing, install Python again. Ensure you check "Add Python to PATH" during installation on Windows.

Outdated pip: Update pip first:

pip install --upgrade pip

Then try installing Textual again.

Terminal not supported: Textual works best on modern terminals like Windows Terminal, iTerm2, or GNOME Terminal. Old terminals like the legacy Windows cmd may not display colors correctly. Use a modern terminal for the best experience.

Install a Specific Version

Sometimes you need a specific version of Textual. Use the == syntax:

pip install textual==0.50.0

Replace 0.50.0 with your desired version. Check the official Textual release page for available versions. Sticking to the latest stable version is recommended for most projects.

Uninstall Textual

If you need to remove Textual, use:

pip uninstall textual

This removes the library and its dependencies. Confirm when prompted.

Conclusion

Installing Textual in Python is straightforward. Use pip to get the latest version. For better project management, use a virtual environment. Verify your installation by running a small test app. The dev tools add live reloading for faster development. If you hit issues, check your terminal and update pip.

Now you are ready to build beautiful terminal applications. Start with the official Textual documentation to learn about widgets and layouts. Happy coding!