Install & Compatibility
Where this runs
tested against v30.17.0 · 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
23MB installed
● package 23MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
parse_one
✓ from sqlglot import parse_one
✗ sqlglot.parse_one(sql)
Commonly imported directly for convenience; the root module also provides it.
transpile
✓ from sqlglot import transpile
✗ sqlglot.transpile(sql)
Commonly imported directly for convenience; the root module also provides it.
exp
✓ from sqlglot import exp
✗ sqlglot.expressions as exp
The `exp` submodule contains all expression types for AST manipulation and is typically imported directly from the root `sqlglot` module now.
This quickstart demonstrates basic SQL parsing and cross-dialect transpilation. The `parse_one` function converts a SQL string into an Abstract Syntax Tree (AST), while `transpile` converts SQL between specified dialects. It also shows a common pattern for transforming MySQL-specific functions to BigQuery equivalents.
from sqlglot import parse_one, transpile
# Parse a SQL query (defaults to SQLGlot dialect if 'read' is not specified)
sql_query = "SELECT id, name FROM users WHERE age > 18"
expression = parse_one(sql_query)
print(f"Parsed Expression: {expression}")
# Transpile from MySQL to BigQuery
mysql_query = "SELECT IFNULL(employee_name, 'Unknown') AS employee_status FROM employees;"
bigquery_query = transpile(mysql_query, read="mysql", write="bigquery")[0]
print(f"Transpiled to BigQuery: {bigquery_query}")
# Further manipulation of the AST is possible with `expression` object
# E.g., print(expression.find_all(exp.Column))
sqlglot --version
Debug
Known issues
gotchaFailing to specify the `read` (source) or `write` (target) dialect during `parse_one` or `transpile` calls can lead to `ParseError` or incorrect output. SQLGlot defaults to its 'SQLGlot dialect', which is a superset, if not specified.fixAlways specify `read='your_source_dialect'` when parsing and `write='your_target_dialect'` when transpiling for accurate results (e.g., `parse_one(sql, read='spark')`).
affects: All versions
gotchaSQLGlot strictly parses valid SQL. It will raise a `ParseError` if the SQL string contains non-SQL constructs like templating variables (e.g., `{{parameter}}`) or invalid syntax (e.g., unquoted timestamps in some contexts).fixPre-render or interpolate any non-SQL templating variables before passing the SQL string to SQLGlot. Ensure all SQL literals, especially timestamps, are correctly quoted according to SQL standards.
affects: All versions
breakingSQLGlot's versioning strategy indicates that MINOR version increments (e.g., 29.x to 30.x) can introduce backwards-incompatible fixes or feature additions. Be mindful of minor version bumps during upgrades.fixRefer to the official changelog or release notes for each minor version upgrade to identify potential breaking changes and necessary code adjustments. Test thoroughly before deploying new minor versions.
affects: All versions (since project inception)
gotchaWhile SQLGlot is comprehensive, transpilation across all possible dialect pairs and inputs is an 'incremental' problem. Some specific dialect conversions may have limitations or ongoing improvements.fixIf encountering unexpected transpilation behavior for specific dialect features, consult the SQLGlot documentation, raise an issue on GitHub, or consider contributing a fix.
affects: All versions
gotchaParsing SQL queries with column names or identifiers using non-standard quoting (e.g., backticks as often used by LLMs) can lead to `ParseError`.fixAs a workaround, replace non-standard cross-quotes with standard double quotes (`"`) before parsing, or ensure the input SQL conforms to a supported dialect's quoting conventions.
affects: All versions
gotchaSQLGlot parsing or transpilation can, in rare cases, encounter performance bottlenecks or infinite loops when processing extremely complex or malformed SQL, leading to a 'TIMEOUT' rather than an explicit `ParseError`. This is more likely with very large queries, deeply nested expressions, or highly unusual syntax patterns.fixSimplify complex queries, break down very large SQL statements, or review known performance limitations for specific SQL constructs if encountering consistent timeouts. Consider setting a parsing timeout if the environment supports it to catch such cases gracefully.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'sqlglot'
The 'sqlglot' library is not installed in the current Python environment.
fixInstall the 'sqlglot' library using pip: 'pip install sqlglot'.
ImportError: cannot import name 'transpile' from 'sqlglot'
The 'transpile' function has been moved or renamed in recent versions of 'sqlglot'.
fixUpdate your import statement to: 'from sqlglot import transpile'.
AttributeError: module 'sqlglot' has no attribute 'parse'
The 'parse' function has been deprecated or removed in the current version of 'sqlglot'.
fixUse the 'sqlglot.parse_one' function instead: 'from sqlglot import parse_one'.
TypeError: transpile() got an unexpected keyword argument 'dialect'
The 'transpile' function's signature has changed, and it no longer accepts a 'dialect' keyword argument.
fixRefer to the latest 'sqlglot' documentation for the correct usage of the 'transpile' function.
ValueError: Unsupported dialect 'mysql'
The specified SQL dialect is not supported by the current version of 'sqlglot'.
fixEnsure you are using a supported dialect; refer to the 'sqlglot' documentation for a list of supported dialects.
Upgrade
Version history
30.17.0latest on PyPI · released Aug 12, 2026
Audit
Dependencies
c-extensionsoptionalOptional performance improvement
rust-tokenizeroptionalOptional performance improvement