gast: Generic Python AST

0.7.0 verified Tue May 12 auth: no python install: verified

gast provides a compatibility layer between the Abstract Syntax Trees (AST) of various Python versions (including Python 2 and Python 3), offering a homogeneous API compatible with the standard library `ast` module. It abstracts away version-specific differences in the AST structure, making it easier to write tools that work across multiple Python versions. The library is currently at version 0.7.0 and remains actively maintained.

pip install gast

Common errors

error ModuleNotFoundError: No module named 'gast' ↓

cause The 'gast' library is not installed in the current Python environment or the Python interpreter cannot locate it in its search path.

fix

Install the 'gast' library using pip: pip install gast or ensure your environment variables (like PYTHONPATH) are correctly set if it's installed in a non-standard location.

error AttributeError: module 'gast' has no attribute 'Num' ↓

cause This error typically occurs when a dependent library (like an older version of TensorFlow) expects specific AST nodes (like `Num`, `Str`, `Bytes`) that have been deprecated and replaced by `gast.Constant` in newer `gast` versions (e.g., gast >= 0.3.0 or >= 0.4.0).

fix

Downgrade 'gast' to an older version compatible with the dependent library (e.g., pip install gast==0.2.2 or pip install gast==0.3.3), or upgrade the dependent library to one that supports newer gast versions.

error AttributeError: module 'gast' has no attribute 'Index' ↓

cause Similar to the `Num` error, this indicates a breaking API change in 'gast' where the `Index` AST node (or its equivalent) was removed or modified in a newer version, while an older dependent package still tries to access it.

fix

Downgrade 'gast' to a version compatible with the problematic dependent library (e.g., pip install gast==0.3.3) or update the dependent library to one that supports the current 'gast' version.

error python-gast03 and python-gast are in conflict ↓

cause This is a package management conflict, often encountered with system package managers (like `pacman` on Arch Linux), where different installed packages require mutually exclusive versions of 'gast' (e.g., one requires `python-gast` and another `python-gast03`).

fix

Identify which packages require conflicting 'gast' versions. You may need to remove one of the conflicting packages, or use a virtual environment to isolate the dependencies, or check for updated packages that resolve the conflict (e.g., sudo pacman -R python-gast and then sudo pacman -Syu to allow the update to install python-gast03).

Warnings

breaking For Python 3.8 and later, several `ast` node types like `ast.Num`, `ast.Str`, `ast.Bytes`, `ast.Ellipsis`, and `ast.NamedConstant` are replaced by `gast.Constant` in `gast` ASTs (since `gast >= 0.3.0`). Code that directly inspects or creates these specific node types must be updated to use `gast.Constant` for cross-version compatibility. ↓

fix Replace usages of `gast.Num`, `gast.Str`, etc., with `gast.Constant(value=..., kind=None)` when working with GAST trees, especially when targeting Python 3.8+.

gotcha The representation of certain AST nodes changes in Python 3.9+. For instance, `ast.arg` nodes are represented as `ast.Name` with an `ast.Param` context, and `ExceptHandler.name` is an `ast.Name` with an `ast.Store` context instead of a simple string. ↓

fix When traversing or manipulating GASTs, be aware of these structural changes and use appropriate attribute access or type checks, or rely on `gast`'s conversion functions (`gast.gast_to_ast`, `gast.ast_to_gast`) to handle discrepancies.

gotcha The interpretation of literals like `None`, `True`, and `False` differs between Python 2 and Python 3. In Python 3, they are parsed as `gast.Constant`, while in Python 2, they are parsed as `gast.Name`. ↓

fix When writing tools that target both Python 2 and Python 3 via `gast`, ensure your code can handle these literals potentially being either `gast.Constant` or `gast.Name`.

gotcha While `gast` provides an API compatible with `ast`, directly importing or using classes from the standard `ast` module when you intend to work with `gast`'s cross-version AST can lead to unexpected behavior or `AttributeError` if the underlying `ast` module's structure for that node differs from `gast`'s harmonized representation. ↓

fix Always import and use node types directly from `gast` (e.g., `gast.Name`, `gast.Constant`) when building or manipulating GAST trees to ensure full compatibility and abstraction across Python versions.

gotcha The `_field_types` attribute, which exists for each AST class in standard `ast` modules, is always empty in `gast` for Python versions before 3.10. Relying on this field for introspection might yield incomplete information on older Python versions. ↓

fix Avoid relying on `_field_types` for critical logic if your tool needs to function correctly across a wide range of Python versions. Consider alternative introspection methods or conditional logic based on Python version.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.01s 18.0M

3.10 alpine (musl) - - 0.01s 18.0M

3.10 slim (glibc) wheel 1.5s 0.01s 18M

3.10 slim (glibc) - - 0.01s 18M

3.11 alpine (musl) wheel - 0.02s 19.9M

3.11 alpine (musl) - - 0.03s 19.9M

3.11 slim (glibc) wheel 1.6s 0.02s 20M

3.11 slim (glibc) - - 0.02s 20M

3.12 alpine (musl) wheel - 0.02s 11.8M

3.12 alpine (musl) - - 0.02s 11.8M

3.12 slim (glibc) wheel 1.5s 0.02s 12M

3.12 slim (glibc) - - 0.02s 12M

3.13 alpine (musl) wheel - 0.02s 11.5M

3.13 alpine (musl) - - 0.02s 11.4M

3.13 slim (glibc) wheel 1.5s 0.02s 12M

3.13 slim (glibc) - - 0.02s 12M

3.9 alpine (musl) wheel - 0.01s 17.5M

3.9 alpine (musl) - - 0.01s 17.5M

3.9 slim (glibc) wheel 1.7s 0.01s 18M

3.9 slim (glibc) - - 0.01s 18M

Imports

gast
```
import gast
```
Node
```
from gast import Name, Constant
```
gast provides all standard `ast` nodes, but some might be harmonized across versions (e.g., `gast.Constant`).
parse
wrong
```
ast.parse(code) if expecting a GAST node
```
correct
```
gast.parse(code)
```
gast.parse directly produces a GAST node, unlike ast.parse which produces a standard AST node.

Quickstart last tested: 2026-04-24

This quickstart demonstrates how to parse Python code into a `gast` AST, convert a `gast` AST to a standard `ast` module AST, and convert a standard `ast` to a `gast` AST. The `gast.dump` function is used for easy inspection of the GAST structure.

import gast
import ast

code = """def foo(x):
    return x + 1"""

# Parse code into a GAST (Generic AST) node
gast_tree = gast.parse(code)
print("GAST Tree (using gast.dump):\n" + gast.dump(gast_tree))

# Convert the GAST tree to a standard AST tree for the current Python version
std_ast_tree = gast.gast_to_ast(gast_tree)
print("\nStandard AST Tree (from GAST, using ast.dump):\n" + ast.dump(std_ast_tree))

# Example of converting a standard AST to a GAST tree
std_ast_input = ast.parse("a = 'hello'")
gast_from_std = gast.ast_to_gast(std_ast_input)
print("\nGAST Tree (from standard AST input, using gast.dump):\n" + gast.dump(gast_from_std))