bgt

Fault-tolerant background threads for Python

POV: you want a framework-agnostic way to reliably run a plain1 function or method in the background, repeatedly, but not all the time.

bgt comes to the rescue with:

  • A service that runs your code in a loop and waits between work units. It wakes up on a fixed time interval, or as soon as something wakes it.

  • A supervisor that runs that loop in a background thread. If your code crashes, the supervisor restarts the loop after an exponential backoff. Write crash-only code, bgt takes care of the rest.

  • Thorough instrumentation via structlog and Prometheus.

  • Framework and platform independence.

bgt is the engine underneath pgbg, which adds PostgreSQL LISTEN / NOTIFY-driven wakeups and leader election with automatic failover on top. If your services should wake up on database events, or only one process at a time should do the work, that's where to look.

Background services are not a worker queue. Common use cases include:

  • Periodic cleanup duties for expired caches or sessions.
  • Refreshing in-memory caches or configuration.
  • Flushing buffered metrics or events.

Here's a service that runs a work unit every two seconds and survives its own crashes:

import bgt


def do_work() -> bool:
    ...  # one bounded work unit

    return False  # nothing left to do: wait for the next wakeup


with bgt.SupervisedService.start(
    bgt.as_work_factory(do_work),
    name="example",
    wakeup=bgt.IntervalOnlyWakeup(),
    interval=2,
):
    ...  # do_work runs in the background until we leave this block

Return True from your work unit to be run again immediately. This keeps work units short, which makes shutdowns prompt.

Check out our step-by-step tutorial to get an instant feel for the features!

Installation

The package is available on PyPI under the bgt name:

$ uv pip install bgt

Documentation

Full documentation lives at https://bgt.hynek.me/.

Release Information

Added

  • Initial public release. It is the supervision layer from pgbg to allow using it without a PostgreSQL database. The Prometheus metrics and the structlog logger are named bgt instead of pgbg.

Full Changelog →

Credits

bgt is written by Hynek Schlawack and distributed under the terms of the MIT license.

The development is kindly supported by my employer Variomedia AG and all my fabulous GitHub Sponsors.

  1. As in: not async. ↩

Project links

Data verified by PyPI on Sep 4, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for hynek from gravatar.com hynek

Credits

Author: Hynek Schlawack

GitHub Statistics

Data verified by PyPI on Sep 4, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.12

Tags

background tasks background threads crash-only supervisor

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

bgt-26.1.0.tar.gz (100.7 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

bgt-26.1.0-py3-none-any.whl (12.2 kB view details)

Uploaded Python 3

File details

Details for the file bgt-26.1.0.tar.gz.

File metadata

  • Download URL: bgt-26.1.0.tar.gz
  • Upload date:
  • Size: 100.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for bgt-26.1.0.tar.gz
Algorithm Hash digest
SHA256 33032d188ba9964965b0fb79aa9375a441709a8d1677d327cd9ac79ee33ed0d0
MD5 3af3f9e54a223284a22e3ba6c104a661
BLAKE2b-256 2a64bb1b2ea7b71e2d9dee7657c694d4347d228416905cf4d3593a126f7fd46d

See more details on using hashes here.

Provenance

The following attestation bundles were made for bgt-26.1.0.tar.gz:

Publisher: pypi-package.yml on hynek/bgt

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file bgt-26.1.0-py3-none-any.whl.

File metadata

  • Download URL: bgt-26.1.0-py3-none-any.whl
  • Upload date:
  • Size: 12.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for bgt-26.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 3b8e8abe2e8b4efa8ad94a3f897ae9eb04c57c5c91679b93efc5e33e2165c521
MD5 5614b71b1c64e47d73236ef9a85fb082
BLAKE2b-256 18717b6f10fa55bc7750844b41b6da26697144b599d38f7cabc249cc7d49332c

See more details on using hashes here.

Provenance

The following attestation bundles were made for bgt-26.1.0-py3-none-any.whl:

Publisher: pypi-package.yml on hynek/bgt

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

26.1.0 This release

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page