{"id":15070037,"url":"https://github.com/anonymoux47/term-image","last_synced_at":"2025-12-12T01:02:30.118Z","repository":{"id":37021990,"uuid":"423235543","full_name":"AnonymouX47/term-image","owner":"AnonymouX47","description":"Display images in the terminal with python","archived":false,"fork":false,"pushed_at":"2025-04-05T19:01:44.000Z","size":6271,"stargazers_count":235,"open_issues_count":10,"forks_count":10,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-07T23:03:50.445Z","etag":null,"topics":["cli","curses","image","image-viewer","images","library","pil","pillow","python","python3","terminal","terminal-based","tui"],"latest_commit_sha":null,"homepage":"https://term-image.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AnonymouX47.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"custom":["https://www.buymeacoffee.com/anonymoux47"]}},"created_at":"2021-10-31T18:57:59.000Z","updated_at":"2025-04-05T18:53:30.000Z","dependencies_parsed_at":"2023-10-04T23:03:07.468Z","dependency_job_id":"304c2afc-8adf-4944-ae69-73943ee0f932","html_url":"https://github.com/AnonymouX47/term-image","commit_stats":{"total_commits":1795,"total_committers":8,"mean_commits":224.375,"dds":"0.15431754874651815","last_synced_commit":"05d14397eb9e165a85e0d58c11c6cc8b19ba1113"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AnonymouX47%2Fterm-image","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AnonymouX47%2Fterm-image/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AnonymouX47%2Fterm-image/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AnonymouX47%2Fterm-image/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AnonymouX47","download_url":"https://codeload.github.com/AnonymouX47/term-image/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247744294,"owners_count":20988781,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","curses","image","image-viewer","images","library","pil","pillow","python","python3","terminal","terminal-based","tui"],"created_at":"2024-09-25T01:46:41.008Z","updated_at":"2025-12-12T01:02:24.030Z","avatar_url":"https://github.com/AnonymouX47.png","language":"Python","funding_links":["https://www.buymeacoffee.com/anonymoux47"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003ch1\u003e\u003cb\u003eTerm-Image\u003c/b\u003e\u003c/h1\u003e\n\n\u003cp\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/AnonymouX47/term-image/92ff4b2d2e4731be9e1b2ac7378964ebed9f10f9/docs/source/resources/logo.png\" height=\"200\"\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n\u003cb\u003eDisplay images in the terminal with Python\u003c/b\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n   \u0026#128214; \u003ca href='https://term-image.readthedocs.io'\u003eDocs\u003c/a\u003e\n    \u0026#9553; \n   \u0026#127979; \u003ca href='https://term-image.readthedocs.io/en/stable/start/tutorial.html'\u003eTutorial\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n   \u003ca href='https://pypi.org/project/term-image/'\u003e\n      \u003cimg src='https://img.shields.io/pypi/v/term-image.svg'\u003e\n   \u003c/a\u003e\n   \u003ca href='https://pepy.tech/project/term-image'\u003e\n      \u003cimg src=\"https://pepy.tech/badge/term-image/month\"\u003e\n   \u003c/a\u003e\n   \u003ca href='https://pypi.org/project/term-image/'\u003e\n      \u003cimg src='https://img.shields.io/pypi/pyversions/term-image.svg'\u003e\n   \u003c/a\u003e\n   \u003ca href='https://github.com/psf/black'\u003e\n      \u003cimg src='https://img.shields.io/badge/code%20style-black-000000.svg'\u003e\n   \u003c/a\u003e\n   \u003ca href='https://github.com/AnonymouX47/term-image/actions/workflows/test.yml'\u003e\n      \u003cimg src='https://github.com/AnonymouX47/term-image/actions/workflows/test.yml/badge.svg'\u003e\n   \u003c/a\u003e\n   \u003ca href='https://htmlpreview.github.io/?https://github.com/AnonymouX47/term-image/blob/python-coverage-comment-action-data/htmlcov/index.html'\u003e\n      \u003cimg src='https://raw.githubusercontent.com/AnonymouX47/term-image/python-coverage-comment-action-data/badge.svg'\u003e\n   \u003c/a\u003e\n   \u003ca href='https://term-image.readthedocs.io'\u003e\n      \u003cimg src='https://readthedocs.org/projects/term-image/badge/?version=latest' alt='Documentation Status' /\u003e\n   \u003c/a\u003e\n   \u003cimg src=\"https://img.shields.io/github/last-commit/AnonymouX47/term-image\"\u003e\n   \u003ca href=\"https://twitter.com/intent/tweet?text=Display%20images%20in%20the%20terminal%20with%20Python\u0026url=https://github.com/AnonymouX47/term-image\u0026hashtags=developers,images,terminal,python\"\u003e\n      \u003cimg src=\"https://img.shields.io/twitter/url/http/shields.io.svg?style=social\"\u003e\n   \u003c/a\u003e\n\u003c/p\u003e\n\n\u003c/div\u003e\n\n\n## Contents\n- [Installation](#installation)\n- [Features](#features)\n- [Demo](#demo)\n- [Quick Start](#library-quick-start)\n- [Usage](#usage)\n- [Contribution](#contribution)\n- [Planned Features](#planned-features)\n- [Known Issues](#known-issues)\n- [FAQs](#faqs)\n- [Credits](#credits)\n- [Sponsor This Project](#sponsor-this-project)\n\n\n\u003e ### ⚠️ NOTICE!!! ⚠️\n\u003e The image viewer (CLI and TUI) has been moved to [termvisage].\n\n\n## Installation\n\n### Requirements\n- Operating System: Unix / Linux / Mac OS X / Windows (limited support, see the [FAQs](https://term-image.readthedocs.io/en/stable/faqs.html))\n- [Python](https://www.python.org/) \u003e= 3.9\n- A terminal emulator with **any** of the following:\n  \n  - support for the [Kitty graphics protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/).\n  - support for the [iTerm2 inline image protocol](https://iterm2.com/documentation-images.html).\n  - full Unicode support and direct-color (truecolor) support\n\n  **Plans to support a wider variety of terminal emulators are in motion** (see [Planned Features](#planned-features)).\n\n### Steps\nThe latest **stable** version can be installed from [PyPI](https://pypi.org/project/term-image) with:\n\n```shell\npip install term-image\n```\n\nThe **development** version can be installed with:\n\n```shell\npip install git+https://github.com/AnonymouX47/term-image.git\n```\n\n### Supported Terminal Emulators\nSee [here](https://term-image.readthedocs.io/en/stable/start/installation.html#supported-terminal-emulators) for a list of tested terminal emulators.\n\nIf you've tested this library on any other terminal emulator that meets the requirements for any of the render styles,\nplease mention the name (and version) in a new thread under [this discussion](https://github.com/AnonymouX47/term-image/discussions/4).\n\nAlso, if you have any issue with terminal support, you may report or check information about it in the discussion linked above.\n\n\n## Features\n- Multiple image formats (basically all formats supported by [`PIL.Image.open()`](https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html))\n- Multiple image source types: PIL image instance, local file, URL\n- Multiple image render styles (with automatic support detection)\n- Support for multiple terminal graphics protocols: [Kitty](https://sw.kovidgoyal.net/kitty/graphics-protocol/), [iTerm2](https://iterm2.com/documentation-images.html)\n  - Exposes various features of the protocols\n- Transparency support (with multiple options)\n- Animated image support (including transparent ones)\n  - Multiple formats: GIF, WEBP, APNG (and possibly more)\n  - Fully controllable iteration over rendered frames of animated images\n  - Image animation with multiple parameters\n- Integration into various TUI / terminal-based output libraries.\n- Terminal size awareness\n- Automatic and manual image sizing\n- Horizontal and vertical alignment\n- Automatic and manual font ratio adjustment (to preserve image aspect ratio)\n- and more... 😁\n\n\n## Demo\n\nCheck out this [image viewer][termvisage] based on this library.\n\n\n## Quick Start\n\n### Creating an instance\n\n1. Initialize with a file path:\n   ```python\n   from term_image.image import from_file\n   \n   image = from_file(\"path/to/image.png\")\n   ```\n\n2. Initialize with a URL:\n   ```python\n   from term_image.image import from_url\n   \n   image = from_url(\"https://www.example.com/image.png\")\n   ```\n\n3. Initialize with a PIL (Pillow) image instance:\n   ```python\n   from PIL import Image\n   from term_image.image import AutoImage\n   \n   img = Image.open(\"path/to/image.png\")\n   image = AutoImage(img)\n   ```\n\n### Drawing/Displaying an Image\n\nThere are two basic ways to draw an image to the terminal screen:\n\n1. Using the `draw()` method:\n   ```python\n   image.draw()\n   ```\n   **NOTE:** `draw()` has various parameters for render formatting.\n\n2. Using `print()` with an image render output:\n   ```python\n   print(image)  # without formatting\n   # OR\n   print(f\"{image:\u003e200.^100#ffffff}\")  # with formatting\n   ```\n\nFor animated images, only the former animates the output, the latter only draws the current frame.\n\nSee the [tutorial](https://term-image.readthedocs.io/en/stable/start/tutorial.html) for a more detailed introduction.\n\n\n## Usage\n\n\u003cp align=\"center\"\u003e\u003cb\u003e\n   🚧 Under Construction - There will most likely be incompatible changes between minor versions of\n   \u003ca href='https://semver.org/spec/v2.0.0.html#spec-item-4'\u003eversion zero\u003c/a\u003e!\n\u003c/b\u003e\u003c/p\u003e\n\n**If you want to use this library in a project while it's still on version zero, ensure you pin the dependency to a specific minor version e.g `\u003e=0.4,\u003c0.5`.**\n\nSee the [docs](https://term-image.readthedocs.io) for the User Guide and API Reference.\n\n\n## Contribution\n\nPlease read through the [guidelines](https://github.com/AnonymouX47/term-image/blob/main/CONTRIBUTING.md).\n\nFor code contributions, you should also check out the [Planned Features](#planned-features).\nIf you wish to work on any of the listed features/improvements, please click on the linked issue or go through the [issues](https://github.com/AnonymouX47/term-image/issues) section and join in on an ongoing discussion about the task or create a new issue if one hasn't been created yet, so that the implementation can be discussed.\n\nHint: You can filter issues by *label* or simply *search* using the features's description.\n\nThanks! 💓\n\n\n## Planned Features\n\nSee the [milestones](https://github.com/AnonymouX47/term-image/milestones) and [open issues with the `planned` label](https://github.com/AnonymouX47/term-image/issues?q=label%3A%22planned%22+is%3Aopen).\n\n## Known Issues\n\nSee [here](https://term-image.readthedocs.io/en/stable/issues.html).\n\n## FAQs\n\nSee the [FAQs](https://term-image.readthedocs.io/en/stable/faqs.html) section of the docs.\n\n## Credits\n\nThe following projects have been (and are still) crucial to the development of this project:\n- [Pillow](https://python-pillow.org) by [Fredrik Lundh, Jeffrey A. Clark (Alex) and contributors](https://github.com/python-pillow/Pillow/graphs/contributors)\n- [Requests](https://requests.readthedocs.io) by [Kenneth Reitz and others](https://requests.readthedocs.io/en/latest/dev/authors/)\n\nThe logo was composed using resource(s) from the following source(s):\n- [Gallery icons created by Andrean Prabowo - Flaticon](https://www.flaticon.com/free-icons/gallery)\n\nThis project started as [img](https://github.com/lainq/img) by Pranav Baburaj (but the author had no intentions to take it any further).\n\n## Sponsor This Project\n\n\u003ca href=\"https://www.buymeacoffee.com/anonymoux47\" target=\"_blank\"\u003e\n   \u003cimg src=\"https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png\" alt=\"Buy Me A Coffee\" style=\"height: 60px !important;width: 217px !important;\" \u003e\n\u003c/a\u003e\n\nAny amount will go a long way in aiding the progress and development of this project.\nThank you! 💓\n\n\n[termvisage]: https://github.com/AnonymouX47/termvisage\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanonymoux47%2Fterm-image","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanonymoux47%2Fterm-image","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanonymoux47%2Fterm-image/lists"}