Changelog

The Guppy language is distributed via the guppylang pypi package.

This changelog documents user-facing changes to the Guppy language excluding changes to the compiler internals. The Guppy compiler is versioned with the guppylang-internals package.

Versioning Policy

As of August 2025, The Guppy language is undergoing rapid development and is currently unstable. There is a Guppy v1.0 stability milestone that is a work in progress and subject to change.

0.21.11 (2026-04-01)

Features

Bug Fixes

  • Decouple from tket and pytket dependencies (#1615) (4b704e1)

Documentation

0.21.10 (2026-03-23)

Features

Bug Fixes

Documentation

  • Change return value in enum decorator doc string (#1568) (2201152)

  • Fix docstring typo for measure leaked operation (#1538) (d752510)

  • fix typo in API docs for CH gate definition (#1529) (ef01803)

0.21.9 (2026-02-18)

Features

  • Add function to swap two array elements that lowers to hugr swap op (#1459) (15da521)

  • Add missing bool methods (rxor, rand, ror) (#1498) (6078136)

  • Allow panicking with different signal values (#1461) (e624d4f)

  • Compile time array bounds check for literal indices (#1438) (d2dd890)

  • Lower nat to int conversion to iu_to_s hugr op (#1480) (2ba5720)

  • Make tket a non-optional dependency (#1440) (4af4360)

Bug Fixes

  • Improve docstring formatting array methods (#1499) (4b8ce4c)

  • Upgrade selene-sim version to fix state ordering bug (#1444) (d976df9)

Documentation

0.21.8 (2026-01-09)

Features

  • Add qubit hints on Guppy functions, allowing elision when building emulators (#1378) (b7f10c6), closes #1297

  • Add unsafe array take and put operations (#1165) (7f342e7)

  • update to guppylang-internals 0.27 (#1430) (be02891)

  • Update to hugr v0.15, includes collated_digitstring_counts to extend bitstring collation to digits (#2788) (191c473)

Bug Fixes

0.21.7 (2025-12-15)

Features

Bug Fixes

Miscellaneous Chores

Code Refactoring

  • Implement result using overloads instead of a custom node (#1361) (1da2c5d)

0.21.6 (2025-10-29)

Features

  • implement str() for PartialVector (d85efc9), closes #1225

  • qsystem: add RNG.random_advance() (#1295) (f6271a2)

  • Use borrow_array instead of value_array for array HUGR codegen (#1166) (f9ef42b)

0.21.5 (2025-09-22)

[!WARNING] The .compile() method now assumes the function being compiled is an execution entrypoint and therefore checks it takes no arguments. If you have an existing workflow that produces a HUGR with a non-executable function this will break, use compile_function instead.

Features

  • compile_entrypoint and compile_function methods (#1271) (44883e2)

0.21.4 (2025-09-19)

Features

Bug Fixes

Documentation

Miscellaneous Chores

0.21.3 (2025-08-19)

Features

  • De-deprecate ‘py’ (still just a shorter alias for comptime) (#1202) (32fbee1)

  • Make collections iterable and discardable (#1164) (eb5d817)

Bug Fixes

  • cache state extraction to allow multiple access (#1184) (ac4531c), closes #1183

  • emulator: incorrect pure state check (20651db)

Documentation

  • Extended emulator docs (20651db)

  • Several docstring fixes

0.21.2 (2025-08-11)

Features

  • We can now pass a start and step for the range function just as we can in Python. (#1157) (a1b9333)

  • pin to selene-sim 0.2.0 (#1156) (08c52c0)

  • Update to guppylang-internals 0.22.0

  • Support float parameters as inputs to symbolic circuits loaded with guppy.load_pytket. (#1105) (34c546c), closes #1076 (see example below).

from guppylang import guppy
from guppylang.std.angles import pi
from guppylang.std.quantum import qubit, rx, discard

from pytket import Circuit
from sympy import Symbol

a = Symbol("alpha")

circ = Circuit(1, 1)
circ.Rx(a, 0)
circ.Measure(0, 0)

rx_func = guppy.load_pytket("rx", circ, use_arrays=False)

@guppy
def perform_rx_flip() -> int:
    """Perform an X gate as Rx(q, pi)"""
    q = qubit()
    res = int(rx_func(q, pi))
    discard(q)
    return res

perform_rx_flip.check()

Bug Fixes

  • emulator: pass runtime option to selene (ac969e8)

  • Fix a scoping issue with builtins functions #1122

Documentation

0.21.1 (2025-08-05)

Bug Fixes

Documentation

0.21.0 (2025-08-04)

⚠ BREAKING CHANGES

  • All compiler-internal and non-userfacing functionality is moved into a new guppylang_internals package

  • guppy.compile(foo) and guppy.check(foo) are both now deprecated and will be removed in a future release. Their usage should be replaced with foo.compile() and foo.check().

  • The main function no longer has a special status in Guppy. Any function which takes no arguments can be a valid entrypoint to a program.

  • default HUGR output uses compressed binary encoding.

  • guppylang.tracing.object.GuppyDefinition moved to guppylang.defs.GuppyDefinition guppylang.tracing.object.TypeVarGuppyDefinition moved and renamed to guppylang.defs.GuppyTypeVarDefinition

  • All to_hugr methods on types, arguments, and parameters now require a ToHugrContext CompilableDef.compile_outer now requires a ToHugrContext guppy.hugr_op now passes the compiler context to the function generating the op CheckedFunctionDef now implements MonomorphizableDef instead of CompilableDef CompilerContext.build_compiled_def now requires an instantiation for the definition’s type parameters The ToHugrContext protocol now requires two additional methods: type_var_to_hugr and const_var_to_hugr CompilerContext.{compiled, worklist} and CompilationEngine.compiled are now indexed by a tuple of DefId and optional PartiallyMonomorphizedArgs

  • Any comptime code that previously used constant integers outside the 64-bit signed integer range will now fail to compile.

  • Capturing closures are now disabled by default. Enabling them requires calling guppylang.enable_experimental_features(), however note that they are not supported throughout the stack.

Features

Bug Fixes

  • Allow array comprehension syntax in comptime functions (#1068) (da8f04a), closes #1067

  • Allow struct redefinitions for Python < 3.13 (#1108) (959a4e4), closes #1107

  • Correctly detect [@custom](https://github.com/custom)_guppy_decorator in nested scopes (#1086) (678583c)

  • Fix diagnostics rendering for comptime entrypoints (#1099) (fdd2676), closes #1097

  • Fix frame lookup for Python 3.12 annotation scopes (#1120) (a69e489), closes #1116

  • Fix hugr conversion and bounds checks on numeric literals (#1100) (73d5e92)

  • Fix Jupyter notebook diagnostic rendering (#1109) (6002474)

  • Fix nested function definitions in Python 3.12 (#1064) (090f920)

  • Stop showing temporary variables in comptime diagnostics (#1112) (63854c5), closes #1111

  • support comptime entrypoint (#1079) (721e3dd)

  • Turn capturing closures into experimental feature (#1065) (a959b18)

Documentation

Code Refactoring

  • Split up into guppylang_internals package (#1126) (81d50c0)

0.20.0 (2025-06-19)

⚠ BREAKING CHANGES

Explicit Guppy modules have been removed. Instead, use the regular @guppy decorator everywhere without passing an explicit module. Compilation is now triggered via the .compile method.

0.19.0 syntax

@guppy
def main() -> None:
    ...

guppy.compile_module()

0.20.0 syntax

@guppy
def main() -> None:
    ...

main.compile()

Features

  • with_owned std library function to temporarily take ownership of a borrowed value (#994) (7bf75df), closes #992

  • Add an Either type to the standard library. (#993) (75c1804), closes #991

  • Added a PriorityQueue structure to the standard library.

  • Guppy programs can now include state_result tags which can be used together with Selene to retrieve the statevector at a given point in the program execution (#905) (2217bbc). See the example notebook on Debugging with State Results.

  • Add optional signature argument to RawCustomFunctionDef (#1005) (79e2d5b), closes #1003

  • Add PriorityQueue to standard library (#1006) (4e609f0)

  • Allow users to wrap guppy in their own decorator (#1017) (f047c9b)

  • Comptime nat arguments (#1015) (d2a9a07)

  • diagnostics: add miette bindings for enhanced error rendering (#998) (c8f2724)

  • Function overloading via static dispatch (#1000) (6f523d6). See the corresponding section of the language guide for more information.

  • Remove explicit Guppy modules (#983) (0b2e652)

Bug Fixes

Documentation

  • Fix sphinx autodoc for Guppy functions (#1028) (62f6234)

  • remove wrappers on random docs, add doc to get_current_shot (#1001) (4de4ef2)

  • use the sphinx furo theme for guppy compiler docs (#1031) (e0a767b)

0.19.1 (2025-05-27)

Features

  • Add methods for generating random angles (#979) (129bc5d)

Bug Fixes

0.19.0 (2025-05-22)

⚠ BREAKING CHANGES

  • Bools in HUGRs generated by Guppy are represented using a tket2.bool instead of the HUGR sum type

  • deprecated hresult and qsys_result modules have been removed. Use hugr.qysystem.result directly.

  • Generated HUGRs now refer to entrypoints and are always modules in envelopes.

Features

  • Add stack data structure to standard library (#973) (f82ee42)

  • Bump to Hugr 0.20 and switch to value arrays for lowering (#930) (321b68c)

  • Implement sampling from a generic discrete distribution (#966) (2cb3c6d)

  • Stop emitting non-local edges (#962) (e5e55b1), closes #963

Bug Fixes

  • Specify bash shell in justfile. (#971) (1ec956e)

  • Stop monomorphising higher-order custom function values (#972) (952dba0)

  • stop using value ExtensionSet (#967) (4d47b5f)

Documentation

Code Refactoring

0.18.2 (2025-05-19)

Features

  • Add some explicit copy diagnostic hints (#941) (c99526e)

Bug Fixes

  • Better error message for unsupported generic comptime functions (#951) (35bfbcb), closes #944

  • Capture entire Python scope when defining comptime functions (#952) (898a033), closes #945

  • Fix result / panic / exit calls in comptime functions (#949) (ac4a515)

  • Fix comptime angle arithmetic (#950) (dd0fdc3)

  • Fix resolution of generic lengths in array constructor (#940) (0f1d5db)

  • Fix too narrow rendering of indented diagnostic labels (#933) (94821aa), closes #916

  • typo (#947) (d392ea4)

  • Use correct copyable/droppable terminology for type arg errors (#935) (6a44a1c), closes #867

0.18.1 (2025-04-26)

Features

Bug Fixes

  • add missing compilation for int rshift (#885) (5cd9225), closes #886

  • Allow standalone compilation of pytket functions (#903) (6416513)

  • deprecate zz_max and define in terms of zz_phase (#917) (85f5f6b), closes #914

  • Fix diagnostics spans for dynamically defined notebook functions (#907) (51b1b81), closes #906

0.18.0 (2025-03-25)

⚠ BREAKING CHANGES

  • Lists loaded from py(...) expressions are now turned into immutable frozenarrays instead of regular arrays.

  • Guppy decorators now return instances of GuppyDefinition

Features

0.17.1 (2025-03-24)

Features

Bug Fixes

  • qsystem: remove unsupported random_nat and maybe_rng (635e7ed)

Documentation

0.17.0 (2025-03-18)

⚠ BREAKING CHANGES

  • load_pytket takes arrays by default (pass use_arrays=False for qubit arguments)

  • Option is now a builtin type.

  • angle.{__mul__, __rmul__, __truediv__, __rtruediv__ now take a float instead of an int.

Features

  • add get_current_shot() to qsystem module (#806) (3632ec6)

  • add Option.unwrap_nothing() method (#829) (abb1aa1), closes #810

  • add barrier operation to builtins (#849) (cf0bcfb)

  • Allow array arguments to load_pytket (#858) (37b8b80)

  • Allow explicit application of type arguments (#821) (8f90c04), closes #770

  • Generalise scalar angle operations to float (#824) (d3f5c7f)

  • Implement float to int and nat casts (#831) (b56d66c), closes #794

  • qsystem: add Random number generation module (08fbf47)

  • Switch to improved iterator protocol (#833) (348dfdc)

Bug Fixes

  • Correctly handle assignments of arrays in control-flow (#845) (32ded02), closes #844

  • Define len of arrays using Guppy (#863) (6868ff6), closes #804

  • Fix array comprehensions with generic element type (#865) (50df0db), closes #864

  • Fix compiler diagnostics when calling check instead of compile (#854) (9993338)

  • Fix diagnostic spans for indented code (#856) (d9fc9fd), closes #852

  • Fix error message for conditional shadowing of global variables (#815) (bdaae11), closes #772

  • Fix linearity checking for array copies (#841) (d9b085f), closes #838

  • Fix mutation of nested arrays (#839) (ffb64f9)

  • Fix rendering of line breaks in diagnostics (#819) (75efd22), closes #818

  • Prevent reordering of operations with side-effects (#855) (75eb441)

Documentation

0.16.0 (2025-02-19)

⚠ BREAKING CHANGES

  • CompiledGlobals renamed to CompilerContext

Features

  • add Option.take() for swapping with None (#809) (9a459d5)

Code Refactoring

  • Stop inlining array.getitem and array.setitem (#799) (bb199a0), closes #786

0.15.0 (2025-02-07)

⚠ BREAKING CHANGES

  • classical arrays can no longer be implicitly copied

  • pytket circuits no longer supported by py expressions (use @pytket or load_pytket instead)

Features

Bug Fixes

  • Allow string py expressions in result and panic (#759) (53401cc)

  • Fix error printing for structs defined in notebooks (#777) (b41e0fc)

  • Fix pytest hanging (#754) (9ad02bb)

  • panic on negative exponent in ipow (#758) (821771a)

  • Properly report errors for unsupported subscript assignments (#738) (8afa2a9), closes #736

  • remove newlines in extension description (#762) (2f5eed3)

Documentation

0.14.0 (2024-12-19)

⚠ BREAKING CHANGES

  • Lists in py(...) expressions are now turned into Guppy arrays instead of lists.

  • dirty_qubit function removed

  • measure_return renamed to project_z

Features

Bug Fixes

Documentation

0.13.1 (2024-11-15)

Features

Bug Fixes

0.13.0 (2024-11-12)

⚠ BREAKING CHANGES

  • prelude module renamed to std

Features

Bug Fixes

  • Mock guppy decorator during sphinx builds (#622) (1cccc04)

Documentation

Miscellaneous Chores

Code Refactoring

0.12.2 (2024-10-21)

Features

  • Allow py expressions in type arguments (#515) (b4fae3f)

  • remove python python 3 upper bound (support python 3.13) (#578) (73bb94a), closes #558

Bug Fixes

0.12.1 (2024-09-23)

Features

  • Add Definition.compile producing Hugr Package (#504) (d8c8bec)

  • Add missing tket2 quantum gates, generalise RotationCompile (#510) (18d4b4c)

Miscellaneous Chores

0.12.0 (2024-09-18)

⚠ BREAKING CHANGES

  • Pytket circuits loaded via a py expression no longer take ownership of the passed qubits.

  • Lists and function tensors are no longer available by default. guppylang.enable_experimental_features() must be called before compilation to enable them.

  • The GuppyModule argument is now optional for all decorators and no longer the first positional argument. Removed the explicit module objects builtins, quantum, and angle.

  • quantum_functional is now its own Guppy module and no longer implicitly comes with quantum.

  • Linear function arguments are now borrowed by default; removed the now redundant @inout annotation

Features

  • Add functions to quantum module and make quantum_functional independent (#494) (0b0b1af)

  • Hide lists and function tensors behind experimental flag (#501) (c867f48)

  • Make linear types @inout by default; add @owned annotation (#486) (e900c96)

  • Only lower definitions to Hugr if they are used (#496) (cc2c8a4)

  • Support implicit modules for all decorators and turn builtins into implicit module (#476) (cc8a424)

  • Use inout for pytket circuits (#500) (a980ec2)

Bug Fixes

0.11.0 (2024-09-11)

⚠ BREAKING CHANGES

  • guppy.take_module renamed to guppy.get_module and no longer removes the module from the state.

  • Quantum operations rx, rz, phased_x, and zz_max use the angle type instead of floats.

Features

Bug Fixes

  • hseries ops use floats instead of angles (#483) (7ed3853), closes #477

  • Keep track of definitions that are implicitly imported (#481) (a89f225), closes #480

0.10.0 (2024-09-11)

⚠ BREAKING CHANGES

  • Bumped the hugr dependency to 0.8.0

  • GuppyModule.load no longer loads the content of modules but instead just brings the name of the module into scope. Use GuppyModule.load_all to get the old behaviour.

  • Removed guppylang.hugr_builder.hugr.Hugr, compiling a module returns a hugr.Package instead.

Features

Bug Fixes

Documentation

  • Update readme, cargo build instead of --extra validation (#471) (c2a4c86)

Miscellaneous Chores

0.9.0 (2024-08-12)

⚠ BREAKING CHANGES

Bug Fixes

0.8.1 (2024-08-08)

Bug Fixes

0.8.0 (2024-07-30)

Features

Bug Fixes

  • Use places in BB signatures for Hugr generation (#342) (48b0e35)

0.7.0 (2024-07-25)

⚠ BREAKING CHANGES

  • qubits are now reset on allocation

Features

  • qubits are now reset on allocation, and dirty_qubit added (#325) (4a9e205)

  • Allow access to struct fields and mutation of linear ones (#295) (6698b75), closes #293

  • Allow redefinition of names in guppy modules (#326) (314409c), closes #307

Bug Fixes

  • Use correct hook for error printing inside jupyter notebooks (#324) (bfdb003), closes #323

0.6.2 (2024-07-10)

Features

  • update to hugr-python 0.4 (af770c3)

0.6.1 (2024-07-09)

Features

0.6.0 (2024-07-02)

Features

Bug Fixes

0.5.2 (2024-06-13)

Bug Fixes

0.5.1 (2024-06-12)

Bug Fixes

0.5.0 (2024-06-10)

Features

0.4.0 (2024-05-30)

Features

0.3.0 (2024-05-22)

Features

Bug Fixes

  • Consider type when deciding whether to pack up returns (#212) (4f24a07)

  • Mypy tket2 error (#220) (7ad3908)

  • Only use path when determining equality of implicit modules (#216) (6f47d4b)

  • Serialisation of float values (#219) (937260a), closes #218

Documentation

0.2.0 (2024-04-11)

⚠ BREAKING CHANGES

  • Make qubit type lower case (#165)

Features

Bug Fixes

Documentation

  • add reference to runner to readme (#129) (45c2bf0)

  • Add short description and simplify readme for pypi (#136) (667bba3)

Code Refactoring

Continuous Integration

  • Use release-please bootstrap’s default config (#187) (72e666a)

0.1.0

First release of Guppy! 🐟

This is an alpha release that implements basic language features and compilation to hugr v0.1.