Extensions - Xonsh 0.25.0 Documentation - Python-powered shell for Linux, macOS, Windows, Android. Alternative to PowerShell, cmd, Fish, Nushell, Zsh, Bash

xonsh is an extensible, user-patchable platform: third-party developers can build and distribute their own extensions without going through the xonsh release cycle, and end users can reshape any subsystem directly from their xonsh RC because every part of xonsh is a Python module. In the xonsh ecosystem these extensions are called xontribs.
a set of aliases — plain strings, lists, or callable Python functions
a tab-completer for a single command or a whole API
a prompt field (e.g. battery, container, version-control, kubernetes)
a handler for session events such as on_chdir, on_postcommand, or on_pre_prompt
a new environment variable or $XONSH_* setting
a full subsystem — syntax-highlighting tokens, a history backend, an integration with an external tool, and so on
Two good places to look for xontribs published by the community:
Awesome xontribs — curated list of xontribs.
GitHub xontrib topic — every repository tagged with the xontrib topic on GitHub.
The xontrib command allows you to list the installed xontribs. This command will report if they are loaded in the current session. To display this information, pass the list action to the xontrib command:
For programmatic access, you may also have this command print a JSON formatted string:
Xontribs may be loaded in a few different ways: from your xonsh RC, dynamically at runtime with the xontrib command, or its Python API.
Extensions are loaded via the xontrib load command. This command may be run from anywhere in your xonsh RC or at any point after xonsh has started up.
Pass -s (--suppress-warnings) to load every xontrib that is installed and silently skip any name that isn’t. Useful in a xonsh RC that is shared across machines where only a subset of xontribs is installed.
The same can be done in Python as well
A xontrib can be unloaded from the current session using xontrib unload
Xontribs can use setuptools entrypoints to mark themselves available for autoloading using the below format.
Here the module should contain _load_xontrib_ function as described above.
Please make sure that importing the xontrib module and calling _load_xontrib_ is fast enough. Otherwise it will affect the shell’s startup time. Any other imports or heavy computations should be done in lazy manner whenever possible.
The fastest way to start a new xontrib is the xontrib-template repository — a ready-to-publish skeleton, packaging metadata, and the entry point pre-wired for autoloading.
Xontribs are modules with some special functions written in either xonsh (*.xsh) or Python (*.py).
The xontrib must implement _unload_xontrib_ itself. If this function is not provided, any registered event handlers, environment variables, aliases, and completers will remain active after xontribs unload/reload.
This _load_xontrib_() function is called after your extension is imported, and the currently active xonsh.built_ins.XonshSession instance is passed as the argument.
Xontribs without _load_xontrib_ are still supported. But when such xontrib is loaded, variables listed in __all__ are placed in the current execution context if defined.
Normally, these are stored and found in an implicit namespace package called xontrib. However, xontribs may be placed in any package or directory that is on the $PYTHONPATH.
If a module is in the xontrib namespace package, it can be referred to just by its module name. If a module is in any other package, then it must be referred to by its full package path, separated by . like you would in an import statement. Of course, a module in xontrib may be referred to with the full xontrib.myext. But just calling it myext is a lot shorter and one of the main advantages of placing an extension in the xontrib namespace package.
Here is a sample file system layout and what the xontrib names would be:
You can also use the xontrib template to easily create the layout for your xontrib package.
To register a xontrib, create a PullRequest at awesome-xontribs repository. Also, if you use Github to host your code, please add xonsh and xontrib to the topics.
All of this let’s users know that your xontrib is out there, ready to be used. Of course, you’re under no obligation to register your xontrib. Users will still be able to load your xontrib, as long as they have it installed.
Events – using events in xontribs
Environment – registering environment variables for your xontrib
Tab-Completion – writing custom completers
Awesome-xontribs – registry of community xontribs
Xontrib template – quickstart template