PyMySQL: a pure-Python MySQL client without C extensions

A pure-Python MySQL connector for portable deployments

PyMySQL is a MySQL and MariaDB client written entirely in Python, with no C extensions. It implements PEP 249, the Python database API standard, which ensures consistent interfaces across different database drivers. The pure-Python approach means PyMySQL runs unchanged on CPython 3.9 and later as well as PyPy, without requiring compilation or platform-specific binaries. The no-native-extension design eliminates build-time compilation; you install it via pip on any platform and it works immediately. The tradeoff is that PyMySQL cannot match the raw speed of C-based drivers like mysqlclient, but portable code and simpler deployments often matter more than marginal latency gains. The pyproject.toml lists development status as Production/Stable, and recent versions came out in mid-September 2026. Last push was on 2026-09-23, within the past week.

Installation and your first query

Install PyMySQL with pip:

python3 -m pip install PyMySQL

If you need the sha256_password or caching_sha2_password authentication methods, install with the rsa extra:

python3 -m pip install PyMySQL[rsa]

For MariaDB's ed25519 authentication, use the ed25519 extra:

python3 -m pip install PyMySQL[ed25519]

Once installed, create a connection and execute a query. The README shows a complete example: open a connection with pymysql.connect(), pass a cursorclass to control result format, and use a context manager to ensure cleanup:

import pymysql.cursors

connection = pymysql.connect(
    host="localhost",
    user="user",
    password="passwd",
    database="db",
    cursorclass=pymysql.cursors.DictCursor,
)

with connection:
    with connection.cursor() as cursor:
        sql = "INSERT INTO `users` (`email`, `password`) VALUES (%s, %s)"
        cursor.execute(sql, ("[email protected]", "very-secret"))
    connection.commit()

The context manager (with connection) ensures the connection is closed even if an exception occurs. PyMySQL is not autocommit by default, so you must call connection.commit() after writes. Without the commit, changes are rolled back when the connection closes. By default, cursors return tuples; the DictCursor class shown here returns dictionaries keyed by column name, which simplifies access to result rows.

No async or connection pooling built in

PyMySQL is synchronous. Each cursor.execute() call blocks until the server responds, and there is no native async interface. If your application is async-first, or if you need to handle hundreds of concurrent connections, PyMySQL forces you to manage worker threads or processes yourself, or to reach for an async driver. The README does not mention connection pooling either; for production use you will need to wrap the connect() calls with a pooling library like SQLAlchemy or DBUtils. This design keeps PyMySQL simple and portable, but it places the burden of concurrency on the user.

Authentication options and dependencies

PyMySQL handles the most common authentication: username and password. Modern MySQL deployments also support sha256_password and caching_sha2_password, which require the cryptography library; PyMySQL makes it optional, so you add cryptography only if you need those methods. MariaDB users who use ed25519 authentication need PyNaCl. The pyproject.toml file declares these as optional dependencies under rsa and ed25519, keeping the base package lightweight. If you use password-based auth with a standard MySQL or MariaDB configuration, you need only PyMySQL itself with no additional packages.

PEP 249 compliance and broader ecosystem integration

PyMySQL implements PEP 249, the Python Database API Specification v2.0. This standard interface means that code written for PyMySQL can be adapted to work with other databases like PostgreSQL (via psycopg) or SQLite (via sqlite3) with minimal changes. Many Python ORM frameworks depend on this standard: SQLAlchemy and Django ORM both support PyMySQL as a backend driver. The pyproject.toml lists PyMySQL with zero dependencies, so the base install is just one package. The optional dependencies for authentication are only for specific MySQL auth methods, not for core database operations. This modularity means you pay only for what you use.

Alternatives: async drivers and C-based connectors

For async Python code, asyncmy is an async MySQL client that implements asyncio conventions and works with async/await. asyncmy is the choice if your codebase is already async, whereas PyMySQL is simpler if you are synchronous. If raw speed is the priority, mysqlclient is a pure C wrapper around libmysqlclient, the official MySQL client library. mysqlclient is faster than PyMySQL because it does not interpret the protocol in Python, but it requires compilation at install time and will not run on PyPy. PyMySQL trades speed for portability.

Who should use PyMySQL

Adopt PyMySQL when portability matters. If you deploy Python code across platforms where compiling C extensions is difficult or forbidden, or if you use PyPy for performance, PyMySQL installs everywhere pip works. It also suits single-machine scripts or small web applications where async and high concurrency are not requirements. The requirement to call connection.commit() by hand is explicit and prevents accidental data loss, which some teams prefer. If you use an ORM like SQLAlchemy or Django ORM, both can use PyMySQL as the underlying driver, and the ORM handles pooling and commit logic.

Maintenance, licensing and documentation

PyMySQL is marked Development Status 5 - Production/Stable in pyproject.toml, and recent releases came out on 2026-09-17. It is MIT licensed, with no restrictions on commercial use or modification. The pyproject.toml lists Python 3.9 as the minimum requirement, and the README specifies MySQL and MariaDB LTS versions as the supported target systems. The documentation is hosted at https://pymysql.readthedocs.io/, and the project includes a SECURITY.md file for responsible disclosure of vulnerabilities.

Editorial conclusion

Adopt PyMySQL when you need a portable MySQL client for CPython or PyPy without C compilation hassles, or when your deployment environment cannot install compiled extensions. Skip it if your workload is async-first; PyMySQL has no native async support, and you would be better served by asyncmy or asyncpg. Verify that your target MySQL version matches the LTS releases the README documents.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. PyMySQL/PyMySQL on GitHub
4. README
5. Releases