Install & Compatibility
Where this runs
tested against v4.3.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.144s · 20.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.9s · import 0.132s · 21MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
parse
✓ from astroid import parse
Entry point for parsing Python code into an astroid AST.
MANAGER
✓ from astroid import MANAGER
✗ from astroid.manager import AstroidManager
While 'AstroidManager' exists, 'MANAGER' is the common singleton instance for managing ASTs and inference.
FunctionDef
✓ from astroid.nodes import FunctionDef
✗ from astroid import FunctionDef
Direct import of node classes from the top-level `astroid` package is deprecated since v4.1.0 and will be removed in v5. Import from `astroid.nodes` instead.
AstroidBuilder
✓ from astroid.builder import AstroidBuilder
Used to build ASTs, particularly when custom options or manager instances are needed.
This quickstart demonstrates parsing a Python code string into an Astroid AST. It then iterates through the top-level nodes of the module to identify function definitions and their arguments. It also shows a basic traversal within a function to find specific name usages (e.g., 'print').
from astroid import parse
from astroid.nodes import Module, FunctionDef, Name
code = """
def greet(name):
return f"Hello, {name}!"
def farewell(name):
print(f"Goodbye, {name}.")
"""
# Parse the code into an Astroid module
module_node: Module = parse(code)
print(f"Module name: {module_node.name}")
# Iterate over nodes to find functions
for node in module_node.body:
if isinstance(node, FunctionDef):
print(f" Found function: {node.name}")
# Access arguments
for arg in node.args.args:
print(f" Argument: {arg.name}")
# Example: Find 'print' calls (simple traversal)
for child_node in node.body:
if isinstance(child_node, Name) and child_node.name == 'print':
print(f" Function '{node.name}' uses 'print'.")
Debug
Known issues
breakingAstroid v3.0.0 and later removed support for Python 3.7.fixUpgrade your Python environment to 3.8 or newer. Current Astroid versions (4.x) require Python >=3.10.0.
affects: >=3.0.0
breakingIn Astroid v4.0.0, the `manager` argument to `AstroidBuilder()` became required to alleviate circular import issues.fixEnsure you pass a manager instance, typically `astroid.MANAGER`, when initializing `AstroidBuilder`. E.g., `builder = AstroidBuilder(manager=astroid.MANAGER)`.
affects: >=4.0.0
deprecatedImporting node classes directly from the top-level `astroid` package (e.g., `from astroid import FunctionDef`) is deprecated.fixImport node classes from `astroid.nodes` instead (e.g., `from astroid.nodes import FunctionDef`).
affects: >=4.1.0 (to be removed in v5)
gotchaDeeply nested code structures or complex transformations can lead to `RecursionError` during AST processing.fixIncrease Python's recursion limit if encountering such errors: `import sys; sys.setrecursionlimit(YOUR_HIGHER_LIMIT)`.
affects: All versions, but logged as UserWarning with fix instructions since >=4.1.2
breakingAstroid v3.3.0 and later removed support for Python 3.8.fixUpgrade your Python environment to 3.9 or newer. Current Astroid versions (4.x) require Python >=3.10.0.
affects: >=3.3.0
breakingInternal functions `infer_numpy_member`, `name_looks_like_numpy_member`, and `attribute_looks_like_numpy_member` were removed from `astroid.brain.brain_numpy_utils`.fixAvoid using these internal functions directly, as they are no longer part of the public API. Adapt code to use public inference methods.
affects: >=4.0.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'astroid'
The 'astroid' package is not installed in the Python environment.
fixInstall the 'astroid' package using pip: 'pip install astroid'.
ImportError: No module named 'astroid'
The 'astroid' package is not installed or not accessible in the Python environment.
fixEnsure 'astroid' is installed and accessible: 'pip install astroid'.
SyntaxError: invalid syntax
Using Python 2 syntax in a Python 3 environment, such as 'except ValueError, ex:'.
fixUpdate the syntax to be compatible with Python 3: 'except ValueError as ex:'.
E0401: Unable to import 'mytool' (import-error)
Pylint cannot resolve the import due to relative import issues or missing '__init__.py' files.
fixEnsure all necessary '__init__.py' files are present and consider using absolute imports.
F0002: %s: %s
An unexpected error occurred while building the Astroid representation, often due to internal issues.
fixCheck the traceback for details and consider reporting the issue to the Astroid maintainers.
Upgrade
Version history
4.3.1latest on PyPI · released Aug 17, 2026
Audit
Dependencies
typing-extensions>=4optionalRequired for type hint compatibility in Python versions prior to 3.11, when used with astroid's Python >=3.10.0 requirement.