SQLGlot: SQL Parser, Transpiler, and Optimizer

30.1.0 verified Tue May 12 auth: no python install: draft quickstart: verified

SQLGlot is a powerful Python library for parsing, transpiling, optimizing, and even executing SQL. It supports translating SQL across over 30 different database dialects, enabling cross-dialect compatibility, query parsing into Abstract Syntax Trees (ASTs), programmatic query rewriting, and optimization. It's known for being a fast, pure-Python solution with no external dependencies and is regularly among the top Python package downloads. The library is currently at version 30.1.0 and follows a versioning strategy where MINOR version increments can introduce backwards-incompatible changes.

pip install sqlglot

Common errors

error ModuleNotFoundError: No module named 'sqlglot' ↓

cause The 'sqlglot' library is not installed in the current Python environment.

fix

Install the 'sqlglot' library using pip: 'pip install sqlglot'.

error ImportError: cannot import name 'transpile' from 'sqlglot' ↓

cause The 'transpile' function has been moved or renamed in recent versions of 'sqlglot'.

fix

Update your import statement to: 'from sqlglot import transpile'.

error AttributeError: module 'sqlglot' has no attribute 'parse' ↓

cause The 'parse' function has been deprecated or removed in the current version of 'sqlglot'.

fix

Use the 'sqlglot.parse_one' function instead: 'from sqlglot import parse_one'.

error TypeError: transpile() got an unexpected keyword argument 'dialect' ↓

cause The 'transpile' function's signature has changed, and it no longer accepts a 'dialect' keyword argument.

fix

Refer to the latest 'sqlglot' documentation for the correct usage of the 'transpile' function.

error ValueError: Unsupported dialect 'mysql' ↓

cause The specified SQL dialect is not supported by the current version of 'sqlglot'.

fix

Ensure you are using a supported dialect; refer to the 'sqlglot' documentation for a list of supported dialects.

Warnings

gotcha Failing 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. ↓

fix Always specify `read='your_source_dialect'` when parsing and `write='your_target_dialect'` when transpiling for accurate results (e.g., `parse_one(sql, read='spark')`).

gotcha SQLGlot 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). ↓

fix Pre-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.

breaking SQLGlot'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. ↓

fix Refer 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.

gotcha While 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. ↓

fix If encountering unexpected transpilation behavior for specific dialect features, consult the SQLGlot documentation, raise an issue on GitHub, or consider contributing a fix.

gotcha Parsing SQL queries with column names or identifiers using non-standard quoting (e.g., backticks as often used by LLMs) can lead to `ParseError`. ↓

fix As 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.

gotcha SQLGlot 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. ↓

fix Simplify 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.

Install

pip install "sqlglot[c]"

pip install "sqlglot[rs]"

Install compatibility draft last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) c build_error - 0.1s - -

3.10 alpine (musl) rs build_error - 0.1s - -

3.10 alpine (musl) sqlglot wheel - 0.30s 23.3M

3.10 alpine (musl) c - - - -

3.10 alpine (musl) rs - - - -

3.10 alpine (musl) sqlglot - - 0.29s 23.2M

3.10 slim (glibc) c wheel 3.0s 0.22s 103M

3.10 slim (glibc) rs wheel 3.5s 0.26s 103M

3.10 slim (glibc) sqlglot wheel 2.1s 0.18s 24M

3.10 slim (glibc) c - - 0.36s 71M

3.10 slim (glibc) rs - - 0.20s 71M

3.10 slim (glibc) sqlglot - - 0.18s 24M

3.11 alpine (musl) c build_error - 0.1s - -

3.11 alpine (musl) rs build_error - - - -

3.11 alpine (musl) sqlglot wheel - 0.56s 26.8M

3.11 alpine (musl) c - - - -

3.11 alpine (musl) rs - - - -

3.11 alpine (musl) sqlglot - - 0.62s 26.6M

3.11 slim (glibc) c wheel 3.0s 0.36s 108M

3.11 slim (glibc) rs wheel 3.3s 0.36s 108M

3.11 slim (glibc) sqlglot wheel 2.2s 0.47s 27M

3.11 slim (glibc) c - - 0.33s 75M

3.11 slim (glibc) rs - - 0.32s 75M

3.11 slim (glibc) sqlglot - - 0.46s 27M

3.12 alpine (musl) c build_error - 0.1s - -

3.12 alpine (musl) rs build_error - - - -

3.12 alpine (musl) sqlglot wheel - 0.39s 18.4M

3.12 alpine (musl) c - - - -

3.12 alpine (musl) rs - - - -

3.12 alpine (musl) sqlglot - - 0.42s 18.3M

3.12 slim (glibc) c wheel 2.7s 0.32s 103M

3.12 slim (glibc) rs wheel 3.3s 0.34s 103M

3.12 slim (glibc) sqlglot wheel 2.0s 0.40s 19M

3.12 slim (glibc) c - - 0.34s 69M

3.12 slim (glibc) rs - - 0.33s 69M

3.12 slim (glibc) sqlglot - - 0.42s 19M

3.13 alpine (musl) c build_error - 0.1s - -

3.13 alpine (musl) rs build_error - 0.1s - -

3.13 alpine (musl) sqlglot wheel - 0.35s 18.2M

3.13 alpine (musl) c - - - -

3.13 alpine (musl) rs - - - -

3.13 alpine (musl) sqlglot - - 0.36s 18.0M

3.13 slim (glibc) c wheel 3.0s 0.28s 101M

3.13 slim (glibc) rs wheel 3.2s 0.29s 101M

3.13 slim (glibc) sqlglot wheel 2.0s 0.33s 19M

3.13 slim (glibc) c - - 0.29s 68M

3.13 slim (glibc) rs - - 0.29s 68M

3.13 slim (glibc) sqlglot - - 0.35s 18M

3.9 alpine (musl) c wheel - 0.25s 22.7M

3.9 alpine (musl) rs wheel - 0.24s 22.8M

3.9 alpine (musl) sqlglot wheel - 0.21s 22.7M

3.9 alpine (musl) c - - - -

3.9 alpine (musl) rs - - - -

3.9 alpine (musl) sqlglot - - 0.25s 22.6M

3.9 slim (glibc) c wheel 2.5s 0.17s 23M

3.9 slim (glibc) rs wheel 3.1s 0.19s 23M

3.9 slim (glibc) sqlglot wheel 2.5s 0.18s 23M

3.9 slim (glibc) c - - 0.21s 70M

3.9 slim (glibc) rs - - 0.20s 70M

3.9 slim (glibc) sqlglot - - 0.35s 23M

Imports

parse_one
wrong
```
sqlglot.parse_one(sql)
```
correct
```
from sqlglot import parse_one
```
Commonly imported directly for convenience; the root module also provides it.
transpile
wrong
```
sqlglot.transpile(sql)
```
correct
```
from sqlglot import transpile
```
Commonly imported directly for convenience; the root module also provides it.
exp
wrong
```
sqlglot.expressions as exp
```
correct
```
from sqlglot import exp
```
The `exp` submodule contains all expression types for AST manipulation and is typically imported directly from the root `sqlglot` module now.

Quickstart verified last tested: 2026-04-24

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))