Skip to content

Installation

To install xnano from PyPI, use pip:

pip install xnano

To add xnano to a project that uses uv, use this command:

uv add xnano

Supported platforms

  • Python: 3.10 to 3.14.
  • Linux: x86_64 and aarch64, with glibc or musl.
  • macOS: Intel and Apple silicon.
  • Windows: x86_64.
  • WebAssembly: Pyodide, in a browser. A browser has no terminal, so a canvas from xnano.new() draws into memory there, and images and sound are not available.

Each platform has a wheel that is already built, so you do not need Rust.

Optional extras

Images and sound are in separate packages, so the core package stays small. An extra installs one of these packages together with xnano. Install only the extras that your program uses:

Extra What it adds Command
image Pictures from PNG, JPEG, GIF and WebP files, also animated pictures pip install "xnano[image]"
audio Notes, melodies, audio files and the microphone pip install "xnano[audio]"

To install the two extras together, use pip install "xnano[image,audio]". In a uv project, use uv add "xnano[image,audio]".

The core package has everything else, for example pixel art, widgets, effects and hooks. If a program uses an extra that is not installed, xnano raises an ImportError. The error message gives the command that installs the extra.

On Linux, xnano plays sound through ALSA, which desktop Linux distributions include. On a computer without a sound device, terminal.speaker.is_available is False. If a program plays a sound on such a computer, xnano raises an error. To prevent this error, check is_available before you play a sound.

Check the installation

xnano includes a demo program. Start it:

python -m xnano

The demo fills the terminal window, and the xnano command starts the same demo. Press a key to leave the opening screen. The left and right arrows change the page, the up and down arrows move the choice of a page, and q stops the demo. The window must have 80 columns and 24 rows or more.

The demo runs without the extras. With the image extra it shows pictures, and with the audio extra it plays sound. If you see the demo, xnano works, and you can continue to Your First Program.