Install & Compatibility
Where this runs
tested against v0.5.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
py 3.10
4/16 runs
4/16 runs
py 3.11
4/16 runs
4/16 runs
py 3.12
4/16 runs
4/16 runs
py 3.13
4/16 runs
4/16 runs
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
%load_ext sql
✓ %load_ext sql
This is an IPython magic command, not a standard Python import. It loads the SQL extension into the notebook or IPython session.
%sql
✓ %sql sqlite:///:memory:
Used for single-line SQL queries or connecting to a database.
%%sql
✓ %%sql
SELECT * FROM my_table;
Used for multi-line SQL queries.
This quickstart demonstrates how to load the `ipython-sql` extension, connect to an in-memory SQLite database, create a table, insert data, and perform a basic select query. It also shows how to use bind parameters for secure variable substitution in queries.
# Load the ipython-sql extension
%load_ext sql
# Connect to an in-memory SQLite database
%sql sqlite:///:memory:
# Create a table
%%sql
CREATE TABLE users (
id INTEGER PRIMARY KEY,
name VARCHAR(50),
email VARCHAR(100)
);
# Insert data into the table
%%sql
INSERT INTO users (name, email) VALUES
('Alice', 'alice@example.com'),
('Bob', 'bob@example.com');
# Select data from the table
result = %sql SELECT * FROM users;
print(result)
# Demonstrate variable substitution (bind parameters)
user_id = 1
user_name = 'Charlie'
# Using bind parameters (:variable)
user_from_db = %sql SELECT * FROM users WHERE id = :user_id;
print(f"User with ID {user_id}: {user_from_db}")
# Using direct substitution ($variable) - use with caution for dynamic SQL
# (Note: %sql --persist is also available for pandas DataFrames)
Debug
Known issues
breakingipython-sql is a 'Legacy project' with development shifted to JupySQL. For new projects or advanced features, consider using JupySQL, which is its maintained successor.fixMigrate to JupySQL for active development and new features. `pip install jupysql`.
affects: All versions post-JupySQL emergence
breakingIncompatible with SQLAlchemy 2.x. Users upgrading SQLAlchemy to version 2.0 or newer may encounter errors.fixDowngrade SQLAlchemy to version 1.4.x (e.g., `pip install sqlalchemy==1.4.46`) or migrate to JupySQL, which aims for SQLAlchemy 2.x compatibility.
affects: 0.5.0 and older with SQLAlchemy 2.x
gotchaDatabase drivers (e.g., psycopg2, pymysql) are NOT installed with `ipython-sql` by default. You must install the appropriate driver separately for your chosen database.fixInstall the necessary database driver: `pip install <driver_name>` (e.g., `pip install psycopg2-binary`, `pip install pymysql`). Some drivers can be installed via `ipython-sql` extras, e.g., `pip install 'ipython-sql[postgresql]'`.
affects: All versions
gotchaCommon `ImportError` or `UsageError: Line magic function `%sql` not found` when running `%load_ext sql`. This often indicates that `ipython-sql` was installed in a different Python environment or Jupyter kernel than the one currently active.fixEnsure `ipython-sql` is installed in the *exact* Python environment/kernel that your Jupyter Notebook or IPython session is using. Use `!pip install ipython-sql` within a notebook cell or verify your `conda` or `venv` setup.
affects: All versions
gotchaQuery results are loaded as lists into memory. Very large result sets can consume significant memory, potentially causing the notebook or browser to hang.fixUse `%config SqlMagic.autolimit = <INT>` to automatically limit results (e.g., `1000`). Note that `displaylimit` only truncates display, not memory usage. If `autopandas` is true, use Pandas `max_rows` instead.
affects: All versions
deprecatedOlder `prettytable` configuration (e.g., `c.SqlMagic.style`) may cause `KeyError: "DEFAULT"` due to deprecated options.fixUpdate `ipython-sql` to the latest version. Review and update notebook configuration files (`ipython_config.py`) to remove deprecated `SqlMagic.style` settings. The default display style is usually sufficient.
affects: Versions older than 0.5.0, or specific configurations with `prettytable`.
gotchaVariable substitution: Using `:variable_name` creates bind parameters passed to the SQL engine (recommended for data). Using `$variable_name` or `{variable_name}` directly substitutes the value into the SQL string before execution (can be a SQL injection risk for untrusted input). Using `${variable_name}` (both) is not supported.fixPrefer bind parameters (`:variable_name`) for injecting data into queries to prevent SQL injection. Use direct substitution (`$variable_name` or `{variable_name}`) only for dynamic SQL constructs (e.g., table names) with trusted inputs. affects: All versions
Upgrade
Version history
0.5.0latest on PyPI · released Feb 27, 2023
Audit
Dependencies
SQLAlchemyrequiredUsed for database connection strings and ORM capabilities.
IPythonrequiredProvides the magic command functionality for Jupyter/IPython notebooks.
database-specific driveroptionalRequired for connecting to a specific database type (e.g., psycopg2 for PostgreSQL, pymysql for MySQL).
pandasoptionalEnables returning query results as DataFrames and persisting DataFrames to the database.