# Terminalle
A modern, minimalist, semi-transparent, fullscreen "drop-down" terminal emulateur
for [freedesktop.org]-compatible desktops (e.g. GNOME, KDE, Cinnamon).
It omits many features common in other terminal emulators, such as tabs,
because it's meant to be used in conjunction with a terminal multiplexer such as [tmux],
which has a solid, mature UI.
See also [tmux mode] for enhanced tmux features.
Based on [VTE].
[freedesktop.org]: https://freedesktop.org
[tmux]: https://tmux.github.io
[tmux mode]: #tmux-mode
[VTE]: https://wiki.gnome.org/Apps/Terminal/VTE
## Dependencies
<details>
<summary><strong>Arch</strong></summary>
```bash
pacman -S gtk4 vte4 python-gobject python-yaml
```
</details>
<details>
<summary><strong>Debian / Ubuntu</strong></summary>
```bash
apt install gir1.2-gtk-4.0 gir1.2-vte-3.91 python3-gi python3-yaml
```
</details>
<details>
<summary><strong>Fedora</strong></summary>
```bash
dnf install gtk4 python3-gobject python3-pyyaml
```
</details>
<details>
<summary><strong>Other systems</strong></summary>
Install these dependencies:
- [GTK-4](https://www.gtk.org/)
- [VTE](https://wiki.gnome.org/Apps/Terminal/VTE)
- [PyGObject](https://pygobject.gnome.org/)
- [PyYAML](https://pyyaml.org/)
</details>
## Install
Terminalle is distributed via PyPI.
Modern systems prefer to manage Python packages
exclusively via the system package manager,
requiring the scary-looking `--break-system-packages` flag otherwise.
As long as you install the [dependencies](#dependencies) via your system package manager (see above),
Terminalle will be the only Python package managed externally,
and should not cause any conflicts with any system packages.
```bash
sudo uv pip install --system terminalle --break-system-packages
# Recommended: Enable auto-start.
# Starts the server automatically (window hidden) on login
# and restarts automatically on toggle if closed.
terminalle auto
```
## Usage
Whichever process runs `terminalle` is the "server".
```bash
# See usage info.
terminalle --help
# Start the server (in this case, as a background job).
# The window is initially hidden by default.
# This is unnecessary if you've enabled auto-start with `terminalle auto`.
terminalle &
```
When toggled on, the terminal window opens on the monitor where the mouse is located.
To move it to a different monitor, move the mouse, then toggle it on again.
Wayland does not allow applications to position their own windows.
Use `Ctrl+Shift+C` and `Ctrl+Shift+V` to access the clipboard.
### Shortcuts
If you use GNOME or KDE,
Terminalle can manage keyboard shortcuts for you:
```bash
# This example enables 2 keyboard shortcuts to toggle the window,
# and 1 keyboard shortcut to shut down the server.
terminalle key --toggle '<Super>Return' --toggle '<Alt>Return' --quit <Super>Backspace'
```
For any other kind of dekstop environment,
you'll have to set up your own shortcuts to invoke these [D-Bus] methods:
```bash
# Toggle window visibility.
dbus-send --session --type=method_call --dest=party.will.Terminalle \
/party/will/Terminalle party.will.Terminalle.Toggle
# Close the window and kill the server.
dbus-send --session --type=method_call --dest=party.will.Terminalle \
/party/will/Terminalle party.will.Terminalle.Quit
```
[D-Bus]: https://www.freedesktop.org/wiki/Software/dbus
### Uninstall
```bash
# If enabled, auto-start should be disabled prior to uninstalling.
# Also disable any keyboard shortcuts.
terminalle no-auto
terminalle no-key
sudo uv pip uninstall --system terminalle --break-system-packages
```
## Configuration
See an [example configuration]. See the defaults in [`settings.py`].
Defaults can be selectively overridden in
`${XDG_CONFIG_HOME:-${HOME}/.config}/terminalle.yaml`.
[example configuration]: terminalle.yaml
[`settings.py`]: terminalle/settings.py
## TMUX MODE
This is the recommended way to use Terminalle.
It enables some alternative tmux keyboard shortcuts,
which would normally be impossible to configure in `.tmux.conf`
since terminal emulators typically cannot handle these key combinations.
Generally replacing the tmux prefix with a simple `Ctrl` modifier,
it cuts the number of keystrokes in half
without requiring you to memorize new shortcuts.
If you're a tmux power-user, this will *change* things for you.
Turn it on by setting `tmux: true` in `terminalle.yaml` (see [configuration]).
The following shortcuts are enabled in tmux mode:
| tmux default | tmux mode | Command |
| -----------: | --------: | :----------------------------------------------------------------- |
| `<Prefix> !` | `Ctrl+!` | `break-pane` |
| `<Prefix> "` | `Ctrl+"` | `split-window` |
| `<Prefix> #` | `Ctrl+#` | `list-buffers` |
| `<Prefix> $` | `Ctrl+$` | `command-prompt -I "#S" "rename-session -- '%%'"` |
| `<Prefix> %` | `Ctrl+%` | `split-window -h` |
| `<Prefix> &` | `Ctrl+&` | `confirm-before -p "kill-window #W? (y/n)" kill-window` |
| `<Prefix> '` | `Ctrl+'` | `command-prompt -T window-target -pindex "select-window -t ':%%'"` |
| `<Prefix> (` | `Ctrl+(` | `switch-client -p` |
| `<Prefix> )` | `Ctrl+)` | `switch-client -n` |
| `<Prefix> ,` | `Ctrl+,` | `command-prompt -I "#W" "rename-window -- '%%'"` |
| `<Prefix> .` | `Ctrl+.` | `command-prompt -T target "move-window -t '%%'"` |
| `<Prefix> :` | `Ctrl+:` | `command-prompt` |
| `<Prefix> ;` | `Ctrl+;` | `last-pane` |
| `<Prefix> =` | `Ctrl+=` | `choose-buffer -Z` |
| `<Prefix> [` | `Ctrl+[` | `copy-mode` |
| `<Prefix> ]` | `Ctrl+]` | `paste-buffer` |
| `<Prefix> {` | `Ctrl+{` | `swap-pane -U` |
| `<Prefix> }` | `Ctrl+}` | `swap-pane -D` |
To reap maximum benefits, add the following to your `.tmux.conf`,
taking care of other common tmux shortcuts that do not get mangled by typical terminal emulators:
```bash
# Generally shorten `<Prefix> <X>` to `Ctrl+<X>` for various `<X>`.
# Note that some commands (e.g. `<Prefix> c` for `new-window`) would conflict with
# established control sequences (`Ctrl+c` should send `SIGINT`) if shortened.
bind -n C-f command-prompt "find-window -Z -- '%%'"
bind -n C-n next-window
bind -n C-o select-pane -t ":.+"
bind -n C-p previous-window
bind -n C-q display-panes
bind -n C-s choose-tree -Zs
bind -n C-t clock-mode
bind -n C-x confirm-before -p "kill-pane #P? (y/n)" kill-pane
bind -n C-Space next-layout
# Resize panes using arrow keys and either `Ctrl` or `Meta`.
bind -n C-Up resize-pane -U
bind -n M-Up resize-pane -U 5
bind -n C-Down resize-pane -D
bind -n M-Down resize-pane -D 5
bind -n C-Left resize-pane -L
bind -n M-Left resize-pane -L 5
bind -n C-Right resize-pane -R
bind -n M-Right resize-pane -R 5
```
This all goes especially well with [Vim Tmux Navigator],
which provides shortened bindings for switching seemlessly between tmux panes and Vim windows.
[configuration]: #configuration
[Vim Tmux Navigator]: https://github.com/christoomey/vim-tmux-navigator
Raw data
{
"_id": null,
"home_page": null,
"name": "terminalle",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "terminal, emulator, drop-down, freedesktop, gdk, gtk, gnome, vte, console, sick",
"author": null,
"author_email": "Will Noble <author@will.party>",
"download_url": "https://files.pythonhosted.org/packages/ff/5c/a1b91abdfbe95b09cc272c508eea5a6b18e57da4c3cf57c6407c91108baf/terminalle-2.0.1.tar.gz",
"platform": null,
"description": "# Terminalle\n\nA modern, minimalist, semi-transparent, fullscreen \"drop-down\" terminal emulateur\nfor [freedesktop.org]-compatible desktops (e.g. GNOME, KDE, Cinnamon).\n\nIt omits many features common in other terminal emulators, such as tabs,\nbecause it's meant to be used in conjunction with a terminal multiplexer such as [tmux],\nwhich has a solid, mature UI.\nSee also [tmux mode] for enhanced tmux features.\n\nBased on [VTE].\n\n[freedesktop.org]: https://freedesktop.org\n[tmux]: https://tmux.github.io\n[tmux mode]: #tmux-mode\n[VTE]: https://wiki.gnome.org/Apps/Terminal/VTE\n\n## Dependencies\n\n<details>\n<summary><strong>Arch</strong></summary>\n\n```bash\npacman -S gtk4 vte4 python-gobject python-yaml\n```\n\n</details>\n\n<details>\n<summary><strong>Debian / Ubuntu</strong></summary>\n\n```bash\napt install gir1.2-gtk-4.0 gir1.2-vte-3.91 python3-gi python3-yaml\n```\n\n</details>\n\n<details>\n<summary><strong>Fedora</strong></summary>\n\n```bash\ndnf install gtk4 python3-gobject python3-pyyaml\n```\n\n</details>\n\n<details>\n<summary><strong>Other systems</strong></summary>\n\nInstall these dependencies:\n\n- [GTK-4](https://www.gtk.org/)\n- [VTE](https://wiki.gnome.org/Apps/Terminal/VTE)\n- [PyGObject](https://pygobject.gnome.org/)\n- [PyYAML](https://pyyaml.org/)\n\n</details>\n\n## Install\n\nTerminalle is distributed via PyPI.\nModern systems prefer to manage Python packages\nexclusively via the system package manager,\nrequiring the scary-looking `--break-system-packages` flag otherwise.\n\nAs long as you install the [dependencies](#dependencies) via your system package manager (see above),\nTerminalle will be the only Python package managed externally,\nand should not cause any conflicts with any system packages.\n\n```bash\nsudo uv pip install --system terminalle --break-system-packages\n\n# Recommended: Enable auto-start.\n# Starts the server automatically (window hidden) on login\n# and restarts automatically on toggle if closed.\nterminalle auto\n```\n\n## Usage\n\nWhichever process runs `terminalle` is the \"server\".\n\n```bash\n# See usage info.\nterminalle --help\n\n# Start the server (in this case, as a background job).\n# The window is initially hidden by default.\n# This is unnecessary if you've enabled auto-start with `terminalle auto`.\nterminalle &\n```\n\nWhen toggled on, the terminal window opens on the monitor where the mouse is located.\nTo move it to a different monitor, move the mouse, then toggle it on again.\nWayland does not allow applications to position their own windows.\n\nUse `Ctrl+Shift+C` and `Ctrl+Shift+V` to access the clipboard.\n\n### Shortcuts\n\nIf you use GNOME or KDE,\nTerminalle can manage keyboard shortcuts for you:\n\n```bash\n# This example enables 2 keyboard shortcuts to toggle the window,\n# and 1 keyboard shortcut to shut down the server.\nterminalle key --toggle '<Super>Return' --toggle '<Alt>Return' --quit <Super>Backspace'\n```\n\nFor any other kind of dekstop environment,\nyou'll have to set up your own shortcuts to invoke these [D-Bus] methods:\n\n```bash\n# Toggle window visibility.\ndbus-send --session --type=method_call --dest=party.will.Terminalle \\\n /party/will/Terminalle party.will.Terminalle.Toggle\n\n# Close the window and kill the server.\ndbus-send --session --type=method_call --dest=party.will.Terminalle \\\n /party/will/Terminalle party.will.Terminalle.Quit\n```\n\n[D-Bus]: https://www.freedesktop.org/wiki/Software/dbus\n\n### Uninstall\n\n```bash\n# If enabled, auto-start should be disabled prior to uninstalling.\n# Also disable any keyboard shortcuts.\nterminalle no-auto\nterminalle no-key\n\nsudo uv pip uninstall --system terminalle --break-system-packages\n```\n\n## Configuration\n\nSee an [example configuration]. See the defaults in [`settings.py`].\nDefaults can be selectively overridden in\n`${XDG_CONFIG_HOME:-${HOME}/.config}/terminalle.yaml`.\n\n[example configuration]: terminalle.yaml\n[`settings.py`]: terminalle/settings.py\n\n## TMUX MODE\n\nThis is the recommended way to use Terminalle.\nIt enables some alternative tmux keyboard shortcuts,\nwhich would normally be impossible to configure in `.tmux.conf`\nsince terminal emulators typically cannot handle these key combinations.\nGenerally replacing the tmux prefix with a simple `Ctrl` modifier,\nit cuts the number of keystrokes in half\nwithout requiring you to memorize new shortcuts.\nIf you're a tmux power-user, this will *change* things for you.\nTurn it on by setting `tmux: true` in `terminalle.yaml` (see [configuration]).\n\nThe following shortcuts are enabled in tmux mode:\n\n| tmux default | tmux mode | Command |\n| -----------: | --------: | :----------------------------------------------------------------- |\n| `<Prefix> !` | `Ctrl+!` | `break-pane` |\n| `<Prefix> \"` | `Ctrl+\"` | `split-window` |\n| `<Prefix> #` | `Ctrl+#` | `list-buffers` |\n| `<Prefix> $` | `Ctrl+$` | `command-prompt -I \"#S\" \"rename-session -- '%%'\"` |\n| `<Prefix> %` | `Ctrl+%` | `split-window -h` |\n| `<Prefix> &` | `Ctrl+&` | `confirm-before -p \"kill-window #W? (y/n)\" kill-window` |\n| `<Prefix> '` | `Ctrl+'` | `command-prompt -T window-target -pindex \"select-window -t ':%%'\"` |\n| `<Prefix> (` | `Ctrl+(` | `switch-client -p` |\n| `<Prefix> )` | `Ctrl+)` | `switch-client -n` |\n| `<Prefix> ,` | `Ctrl+,` | `command-prompt -I \"#W\" \"rename-window -- '%%'\"` |\n| `<Prefix> .` | `Ctrl+.` | `command-prompt -T target \"move-window -t '%%'\"` |\n| `<Prefix> :` | `Ctrl+:` | `command-prompt` |\n| `<Prefix> ;` | `Ctrl+;` | `last-pane` |\n| `<Prefix> =` | `Ctrl+=` | `choose-buffer -Z` |\n| `<Prefix> [` | `Ctrl+[` | `copy-mode` |\n| `<Prefix> ]` | `Ctrl+]` | `paste-buffer` |\n| `<Prefix> {` | `Ctrl+{` | `swap-pane -U` |\n| `<Prefix> }` | `Ctrl+}` | `swap-pane -D` |\n\nTo reap maximum benefits, add the following to your `.tmux.conf`,\ntaking care of other common tmux shortcuts that do not get mangled by typical terminal emulators:\n\n```bash\n# Generally shorten `<Prefix> <X>` to `Ctrl+<X>` for various `<X>`.\n# Note that some commands (e.g. `<Prefix> c` for `new-window`) would conflict with\n# established control sequences (`Ctrl+c` should send `SIGINT`) if shortened.\nbind -n C-f command-prompt \"find-window -Z -- '%%'\"\nbind -n C-n next-window\nbind -n C-o select-pane -t \":.+\"\nbind -n C-p previous-window\nbind -n C-q display-panes\nbind -n C-s choose-tree -Zs\nbind -n C-t clock-mode\nbind -n C-x confirm-before -p \"kill-pane #P? (y/n)\" kill-pane\nbind -n C-Space next-layout\n\n# Resize panes using arrow keys and either `Ctrl` or `Meta`.\nbind -n C-Up resize-pane -U\nbind -n M-Up resize-pane -U 5\nbind -n C-Down resize-pane -D\nbind -n M-Down resize-pane -D 5\nbind -n C-Left resize-pane -L\nbind -n M-Left resize-pane -L 5\nbind -n C-Right resize-pane -R\nbind -n M-Right resize-pane -R 5\n```\n\nThis all goes especially well with [Vim Tmux Navigator],\nwhich provides shortened bindings for switching seemlessly between tmux panes and Vim windows.\n\n[configuration]: #configuration\n[Vim Tmux Navigator]: https://github.com/christoomey/vim-tmux-navigator\n",
"bugtrack_url": null,
"license": null,
"summary": "A fancy drop-down terminal emulateur.",
"version": "2.0.1",
"project_urls": {
"Repository": "https://github.com/will/terminalle"
},
"split_keywords": [
"terminal",
" emulator",
" drop-down",
" freedesktop",
" gdk",
" gtk",
" gnome",
" vte",
" console",
" sick"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "720caedae902f3108c12761aceba5bed1c32c33e00848eb3ea90a6dfc330997c",
"md5": "d5b47d85136deaebe491c6c608eee1c1",
"sha256": "390a8ecb8d8c01b1060fad63959643fd8fad37fd3fb498c7c44290cd4c0af6d0"
},
"downloads": -1,
"filename": "terminalle-2.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d5b47d85136deaebe491c6c608eee1c1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 16929,
"upload_time": "2025-10-29T23:38:24",
"upload_time_iso_8601": "2025-10-29T23:38:24.751466Z",
"url": "https://files.pythonhosted.org/packages/72/0c/aedae902f3108c12761aceba5bed1c32c33e00848eb3ea90a6dfc330997c/terminalle-2.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ff5ca1b91abdfbe95b09cc272c508eea5a6b18e57da4c3cf57c6407c91108baf",
"md5": "8df3dea265bb05779e8863b30102aaba",
"sha256": "2118deaec1112e7bdbfe40313dc435a2b86685f9241640f0bea49b234a7fc378"
},
"downloads": -1,
"filename": "terminalle-2.0.1.tar.gz",
"has_sig": false,
"md5_digest": "8df3dea265bb05779e8863b30102aaba",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 18032,
"upload_time": "2025-10-29T23:38:26",
"upload_time_iso_8601": "2025-10-29T23:38:26.111898Z",
"url": "https://files.pythonhosted.org/packages/ff/5c/a1b91abdfbe95b09cc272c508eea5a6b18e57da4c3cf57c6407c91108baf/terminalle-2.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-29 23:38:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "will",
"github_project": "terminalle",
"github_not_found": true,
"lcname": "terminalle"
}
JSON
