{"id":34060320,"url":"https://github.com/iloveitaly/beautiful-traceback","last_synced_at":"2026-02-04T22:15:56.052Z","repository":{"id":321787940,"uuid":"1087184009","full_name":"iloveitaly/beautiful-traceback","owner":"iloveitaly","description":"Beautiful, readable Python tracebacks with colors and formatting","archived":false,"fork":false,"pushed_at":"2026-01-28T18:02:15.000Z","size":3773,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-29T08:45:27.198Z","etag":null,"topics":["debugging","error","formatting","traceback"],"latest_commit_sha":null,"homepage":"https://github.com/iloveitaly/beautiful-traceback","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/iloveitaly.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["iloveitaly"]}},"created_at":"2025-10-31T14:00:44.000Z","updated_at":"2026-01-28T18:01:36.000Z","dependencies_parsed_at":"2026-01-28T20:13:24.391Z","dependency_job_id":null,"html_url":"https://github.com/iloveitaly/beautiful-traceback","commit_stats":null,"previous_names":["iloveitaly/beautiful-traceback"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/iloveitaly/beautiful-traceback","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iloveitaly%2Fbeautiful-traceback","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iloveitaly%2Fbeautiful-traceback/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iloveitaly%2Fbeautiful-traceback/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iloveitaly%2Fbeautiful-traceback/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iloveitaly","download_url":"https://codeload.github.com/iloveitaly/beautiful-traceback/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iloveitaly%2Fbeautiful-traceback/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29097693,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-04T21:05:08.033Z","status":"ssl_error","status_checked_at":"2026-02-04T21:04:53.031Z","response_time":62,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["debugging","error","formatting","traceback"],"created_at":"2025-12-14T04:04:37.760Z","updated_at":"2026-02-04T22:15:56.047Z","avatar_url":"https://github.com/iloveitaly.png","language":"Python","funding_links":["https://github.com/sponsors/iloveitaly"],"categories":[],"sub_categories":[],"readme":"# Beautiful, Readable Python Stack Traces\n\n[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.md)\n[![Python Versions](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)\n\nHuman readable stacktraces for Python.\n\n![Comparison of standard Python traceback vs Beautiful Traceback](comparison.webp)\n\n\u003e [!NOTE]\n\u003e This is a fork of the [pretty-traceback](https://github.com/mbarkhau/pretty-traceback) repo with simplified development and improvements for better integration with FastAPI, [structlog](https://github.com/iloveitaly/structlog-config), IPython, pytest, and more. This project is used in [python-starter-template](https://github.com/iloveitaly/python-starter-template) to provide better debugging experience in production environments.\n\n## Quick Start\n\nThe fastest way to see it in action:\n\n```bash\n# Clone and run an example\ngit clone https://github.com/iloveitaly/beautiful-traceback\ncd beautiful-traceback\nuv run examples/simple.py\n```\n\n## Overview\n\nBeautiful Traceback groups together what belongs together, adds coloring and alignment. All of this makes it easier for you to see patterns and filter out the signal from the noise. This tabular format is best viewed in a wide terminal.\n\n\n## Installation\n\n### From PyPI (when published)\n\n```bash\n# Using uv (recommended)\nuv add beautiful-traceback\n\n# Using pip\npip install beautiful-traceback\n```\n\n### Development Installation\n\nTo install from source:\n\n```bash\ngit clone https://github.com/iloveitaly/beautiful-traceback\ncd beautiful-traceback\nuv sync\n```\n\nRun examples:\n```bash\nuv run examples/simple.py\n```\n\nRun tests:\n```bash\nuv run pytest\n```\n\n## Usage\n\nAdd the following to your `__main__.py` or the equivalent module which is your entry point.\n\n```python\ntry:\n    import beautiful_traceback\n    beautiful_traceback.install()\nexcept ImportError:\n    pass    # no need to fail because of missing dev dependency\n```\n\nPlease do not add this code e.g. to your `__init__.py` or any other module that your users may import. They may not want you to mess with how their tracebacks are printed.\n\nIf you do feel the overwhelming desire to import the `beautiful_traceback` in code that others might import, consider using the `envvar` argument, which will cause the install function to effectively be a noop unless you set `ENABLE_BEAUTIFUL_TRACEBACK=1`.\n\n```python\ntry:\n    import beautiful_traceback\n    beautiful_traceback.install(envvar='ENABLE_BEAUTIFUL_TRACEBACK')\nexcept ImportError:\n    pass    # no need to fail because of missing dev dependency\n```\n\nNote, that the hook is only installed if the existing hook is the default. Any existing hooks that were installed before the call of `beautiful_traceback.install` will be left in place.\n\n## LoggingFormatter\n\nA `logging.Formatter` subclass is also available (e.g. for integration with Flask, FastAPI, etc).\n\n```python\nimport os\nfrom flask.logging import default_handler\n\ntry:\n    if os.getenv('FLASK_DEBUG') == \"1\":\n        import beautiful_traceback\n        default_handler.setFormatter(beautiful_traceback.LoggingFormatter())\nexcept ImportError:\n    pass    # no need to fail because of missing dev dependency\n```\n\n## IPython and Jupyter Integration\n\nBeautiful Traceback works seamlessly in IPython and Jupyter notebooks:\n\n```python\n# Load the extension\n%load_ext beautiful_traceback\n\n# Unload if needed\n%unload_ext beautiful_traceback\n```\n\nThe extension automatically installs beautiful tracebacks for your interactive session.\n\n## Pytest Integration\n\nBeautiful Traceback includes a pytest plugin that automatically enhances test failure output.\n\n### Automatic Activation\n\nThe plugin activates automatically when `beautiful-traceback` is installed. No configuration needed!\n\n### Configuration Options\n\nCustomize the plugin in your `pytest.ini` or `pyproject.toml`:\n\n```toml\n[tool.pytest.ini_options]\nenable_beautiful_traceback = true                    # Enable/disable the plugin\nenable_beautiful_traceback_local_stack_only = true   # Show only local code (filter libraries)\nbeautiful_traceback_exclude_patterns = [             # Regex patterns to drop frames\n  \"click/core\\\\.py\",\n]\n```\n\nOr in `pytest.ini`:\n\n```ini\n[pytest]\nenable_beautiful_traceback = true\nenable_beautiful_traceback_local_stack_only = true\nbeautiful_traceback_exclude_patterns =\n    click/core\\.py\n```\n\nExample: filter out pytest, pluggy, and playwright frames from CI tracebacks:\n\n```toml\n[tool.pytest.ini_options]\nbeautiful_traceback_exclude_patterns = [\n  \"^_pytest/\",\n  \"^pluggy/\",\n  \"^playwright/\",\n]\n```\n\n**Pattern Matching:** Patterns are tested against multiple representations of each frame:\n- `_pytest/runner.py` (short module path)\n- `/path/to/site-packages/_pytest/runner.py` (full module path)\n- `\u003csite\u003e _pytest/runner.py:353 from_call result: ...` (formatted line with short path)\n- `\u003csite\u003e /path/to/.../runner.py:353 from_call result: ...` (formatted line with full path)\n\nThis allows you to write simpler patterns like `^_pytest/` instead of needing to match the full site-packages path.\n\n## Examples\n\nCheck out the [examples/](examples/) directory for detailed usage examples including basic usage, exception chaining, logging integration, and more.\n\n```bash\n# Quick single-exception example\nuv run examples/simple.py\n\n# Interactive demo with multiple exception types\nuv run examples/demo.py\n```\n\n## Configuration\n\n### Installation Options\n\nBeautiful Traceback supports several configuration options:\n\n```python\nbeautiful_traceback.install(\n    color=True,                            # Enable colored output\n    only_tty=True,                         # Only activate for TTY output\n    only_hook_if_default_excepthook=True,  # Only install if default hook\n    local_stack_only=False,                # Filter to show only local code\n    exclude_patterns=[\"click/core\\\\.py\"],  # Regex patterns to drop frames\n    envvar='ENABLE_BEAUTIFUL_TRACEBACK'    # Optional environment variable gate\n)\n```\n\n### Environment Variables\n\n- **`NO_COLOR`** - Disables colored output when set (respects [no-color.org](https://no-color.org) standard)\n- **`ENABLE_BEAUTIFUL_TRACEBACK`** - Controls activation when using the `envvar` parameter (set to `1` to enable)\n\n### LoggingFormatterMixin\n\nFor more advanced logging integration, you can use `LoggingFormatterMixin` as a base class:\n\n```python\nimport logging\nimport beautiful_traceback\n\nclass MyFormatter(beautiful_traceback.LoggingFormatterMixin, logging.Formatter):\n    def __init__(self):\n        super().__init__(fmt='%(levelname)s: %(message)s')\n```\n\nThis gives you full control over the log format while adding beautiful traceback support.\n\n## Global Installation via PTH File\n\nYou can enable beautiful-traceback across all Python projects without modifying any source code by using a `.pth` file. Python automatically executes import statements in `.pth` files during interpreter startup, making this perfect for development environments.\n\n### Using the CLI Command\n\nThe easiest way to inject beautiful-traceback into your current virtual environment:\n\n```bash\nbeautiful-traceback\n```\n\nThis command:\n- Only works within virtual environments (for safety)\n- Installs the `.pth` file into your current environment's site-packages\n- Displays the installation path every time it runs\n\nOutput:\n```\nBeautiful traceback injection installed: /path/to/.venv/lib/python3.11/site-packages/beautiful_traceback_injection.pth\n```\n\n### Using a Shell Function (Alternative)\n\nAlternatively, add this function to your `.zshrc` or `.bashrc`:\n\n```bash\n# Create a file to automatically import beautiful-traceback on startup\npython-inject-beautiful-traceback() {\n  local site_packages=$(python -c \"import site; print(site.getsitepackages()[0])\")\n\n  local pth_file=$site_packages/beautiful_traceback_injection.pth\n  local py_file=$site_packages/_beautiful_traceback_injection.py\n\n  cat \u003c\u003c'EOF' \u003e\"$py_file\"\ndef run_startup_script():\n  try:\n    import beautiful_traceback\n    beautiful_traceback.install(only_tty=False)\n  except ImportError:\n    pass\n\nrun_startup_script()\nEOF\n\n  echo \"import _beautiful_traceback_injection\" \u003e\"$pth_file\"\n  echo \"Beautiful traceback injection created: $pth_file\"\n}\n```\n\nAfter sourcing your shell config, run `python-inject-beautiful-traceback` to enable beautiful tracebacks globally for that Python environment.\n\n## Alternatives\n\nBeautiful Traceback is heavily inspired by the backtrace module by [nir0s](https://github.com/nir0s/backtrace) but there are many others (sorted by github stars):\n\n- https://github.com/qix-/better-exceptions\n- https://github.com/cknd/stackprinter\n- https://github.com/onelivesleft/PrettyErrors\n- https://github.com/skorokithakis/tbvaccine\n- https://github.com/aroberge/friendly-traceback\n- https://github.com/HallerPatrick/frosch\n- https://github.com/nir0s/backtrace\n- https://github.com/mbarkhau/pretty-traceback\n- https://github.com/staticshock/colored-traceback.py\n- https://github.com/chillaranand/ptb\n- https://github.com/laurb9/rich-traceback\n- https://github.com/willmcgugan/rich#tracebacks\n\n## License\n\n[MIT License](LICENSE.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filoveitaly%2Fbeautiful-traceback","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Filoveitaly%2Fbeautiful-traceback","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filoveitaly%2Fbeautiful-traceback/lists"}