Installation¶

sql2sqlx is a pure-Python package with zero runtime dependencies. It runs on Python 3.10 through 3.14 on Linux, macOS and Windows, and ships type information (py.typed), so it type-checks cleanly in downstream projects.

The zero-dependency design is deliberate: the converter is meant to run in migration scripts and CI without pulling a dependency tree, and its lexer and parser are implemented directly on the Python standard library.

From PyPI¶

pip install sql2sqlx

This installs two things:

the sql2sqlx console command (see the CLI reference);
the sql2sqlx Python package (see the API reference).

To upgrade later:

pip install --upgrade sql2sqlx

Tip

Installing into a virtual environment (or with pipx install sql2sqlx for a CLI-only install) keeps it isolated from your system Python.

From source¶

Clone the repository and install in editable mode. The project defines three optional dependency groups:

Extra	Contents
`dev`	`pytest`, `black`, `isort`, `mypy`, `pre-commit` - the test and lint toolchain.
`docs`	`sphinx`, `furo`, `myst-parser`, `myst-nb` - to build this documentation.
`examples`	`jupyter`, `matplotlib` - to run the notebooks and benchmark helper under `examples/`.

git clone https://github.com/neuralsorcerer/sql2sqlx
cd sql2sqlx
pip install -e ".[dev,docs]"
pytest                 # run the test suite

To build the documentation locally after installing the docs extra:

sphinx-build -b html docs docs/_build/html
# or: make -C docs html

Verifying the install¶

sql2sqlx --version
python -c "import sql2sqlx; print(sql2sqlx.__version__)"

Both should print the same version string. A quick end-to-end smoke test (the CLI reads a file or a directory - it does not read from a pipe):

echo "CREATE OR REPLACE TABLE ds.t AS SELECT 1 AS x;" > /tmp/smoke.sql
sql2sqlx /tmp/smoke.sql

which prints a type: "table" action to stdout.

What gets installed where¶

sql2sqlx - the importable package (entry points convert_string, convert_file, convert_directory, plus the data model and errors).
sql2sqlx (console script) - mapped to sql2sqlx.cli:main.
python -m sql2sqlx - the same CLI, runnable as a module.

Nothing else is added to your environment: there are no transitive runtime dependencies to audit.