PyMySQL: zero runtime dependencies, and the commit your connection will not do
MySQL client library for Python
At a glance
- What is it?
- PyMySQL is a pure-Python MySQL and MariaDB client library written against PEP 249, and its manifest has an empty dependencies list. The two things that surprise newcomers are not the API but the packaging, where cryptography and PyNaCl arrive only when you use RSA or ed25519 authentication, and the connection, which is not in autocommit.
- Who is it for?
- PyMySQL suits a service that must talk to MySQL or MariaDB without a compiler in the build image, that is happy with the DB-API 2.0 interface, and that targets a supported LTS release on both sides. It does not suit a project that needs a compiled driver for throughput, or one whose authentication method is missing an extra it never installed.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 6 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- PyMySQL/PyMySQL7,860 ★ · +15
| Repository | 2026-09-22 | 2026-11-15 |
|---|---|---|
| PyMySQL/PyMySQL | 7.8k | 7.9k |
15 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The dependencies list is empty, and cryptography arrives only if you ask
The manifest declares `dependencies = []`. There is nothing to install alongside PyMySQL, which is the whole argument for a pure-Python driver in a build image that has no compiler.
Two extras exist, and each exists for one authentication method. To use `sha256_password` or `caching_sha2_password` for authentication:
$ python3 -m pip install PyMySQL[rsa]To use MariaDB's `ed25519` authentication method:
$ python3 -m pip install PyMySQL[ed25519]The `rsa` extra pulls in cryptography, and `ed25519` pulls in PyNaCl. That is the failure mode worth planning for: a deployment that installs the plain package against a server configured for sha256_password, or MariaDB with ed25519, fails at connect time rather than at install time, because the extra is not in the resolved set.
The documented example is a users table with utf8mb4_bin everywhere
The example schema is small and deliberate:
CREATE TABLE `users` (
`id` int(11) NOT NULL AUTO_INCREMENT,
`email` varchar(255) COLLATE utf8_bin NOT NULL,
`password` varchar(255) COLLATE utf8_bin NOT NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin
AUTO_INCREMENT=1 ;Everything is quoted with backticks, the two text columns use a binary collation so string comparison is case and accent sensitive, and the table defaults to utf8mb4 with utf8mb4_bin. That combination is a reasonable default for identifiers such as email addresses, and a careless default for a password column if you expect case-insensitive matching.
The server side of the support matrix is equally narrow: MySQL LTS versions or MariaDB LTS versions.
connection.commit() is in the example because autocommit is off
The connection call is the familiar DB-API shape, with one option that changes how you read results:
import pymysql.cursors
# Connect to the database
connection = pymysql.connect(
host="localhost",
user="user",
password="passwd",
database="db",
cursorclass=pymysql.cursors.DictCursor,
)Then the insert, with the connection used as a context manager and the values passed as parameters rather than formatted into the string:
with connection:
with connection.cursor() as cursor:
# Create a new record
sql = "INSERT INTO `users` (`email`, `password`) VALUES (%s, %s)"
cursor.execute(sql, ("[email protected]", "very-secret"))
# connection is not autocommit by default. So you must commit to save
# your changes.
connection.commit()The comment in the repository says it plainly: the connection is not autocommit by default, so you must commit to save your changes. An insert inside a `with connection:` block that never reaches `commit()` is not saved.
DictCursor is what makes a row a dict instead of a tuple
`cursorclass=pymysql.cursors.DictCursor` changes the shape of every row you get back, and the example prints what that looks like:
{"password": "very-secret", "id": 1}A dictionary keyed by column name rather than a positional tuple. The cost is that you cannot index by position, and the benefit is that a query which adds a column does not silently shift every value you were reading by index.
Worth knowing when you are porting code written against another driver: a query that returns the same column name twice still collides in a dict, and the parameter style is `%s` placeholders with a sequence as the second argument to `execute`, not named parameters like `:name`.
The distribution is PyMySQL and the import is pymysql
It is worth stating in one line: the package you install is named PyMySQL, the module you import is named pymysql.
So `ModuleNotFoundError: No module named 'pymysql'` almost always means the package is not installed in the interpreter that is running, not that the name is wrong. The install command the README gives is:
$ python3 -m pip install PyMySQLUsing `python3 -m pip` rather than a bare `pip` is the other half of that fix, because it guarantees the installer belongs to the same interpreter that will run your code.
The repository also has a SECURITY.md, an AGENTS.md, a CHANGELOG.md and a mailing list, and support questions are directed to the StackOverflow tag for pymysql rather than to the issue tracker.
Python 3.9 on CPython or PyPy, and the version comes from an attribute
The supported interpreters are stated narrowly: CPython 3.9 and newer, or the latest 3.x version of PyPy. On the server side the requirement is an LTS release of MySQL or of MariaDB, which means a development release of either is out of scope.
Two build details matter if you vendor the package. The project requires setuptools 77 or newer, and it excludes tests from the wheel by listing what to include and what to leave out, `pymysql*` in and `tests*` out.
The version number is not written in pyproject.toml. It is declared dynamic and read from an attribute:
[tool.setuptools.dynamic]
version = {attr = "pymysql.VERSION_STRING"}So the single source of truth for the version is a constant inside the package, which is why the manifest has no `version =` line at all.
Three releases on one day, and the tests have their own ruff exceptions
The release history is dense around September 2026: v1.2.3, v1.2.2 and v1.2.1 were all published on 2026-09-17, and the last push was on 2026-10-30.
The repository root shows how the project is run. `ci/` holds the continuous integration definitions, `codecov.yml` and `.coveragerc` handle coverage, `renovate.json` handles dependency updates, `.readthedocs.yaml` builds the documentation, and `requirements-dev.txt` carries the development dependencies separately from the empty runtime set.
The lint configuration is more revealing than the file list. Ruff excludes the third-party test fixtures, and there are per-file ignores: `pymysql/protocol.py` is exempted from TRY002, the whole test tree from RUF012, and `test_connection.py` from PIE794. Those are the files where the rules are known to fight the code, which is a reasonable place to find out what a protocol implementation actually looks like.
Editorial conclusion
PyMySQL suits a service that must talk to MySQL or MariaDB without a compiler in the build image, that is happy with the DB-API 2.0 interface, and that targets a supported LTS release on both sides. It does not suit a project that needs a compiled driver for throughput, or one whose authentication method is missing an extra it never installed. Verify three things before you ship: whether your server uses sha256_password, caching_sha2_password or MariaDB's ed25519, because each needs the `rsa` or `ed25519` extra installed separately, whether your code calls commit(), since the connection is not autocommit by default, and whether your Python and your server are both on versions the project lists as supported.
Frequently asked questions
What is PyMySQL in Python?
A pure-Python MySQL and MariaDB client library based on PEP 249, the Python database API specification, released under the MIT licence. It has no runtime dependencies, has a Production/Stable classifier, and supports CPython 3.9 and newer or the latest PyPy 3.x.
How do I install PyMySQL in Python?
Run `python3 -m pip install PyMySQL`. If your server uses sha256_password or caching_sha2_password, install the rsa extra with `python3 -m pip install PyMySQL[rsa]`; for MariaDB's ed25519 method use `python3 -m pip install PyMySQL[ed25519]`. Supported servers are MySQL or MariaDB LTS releases.
how to use pymysql
Connect with `pymysql.connect(host, user, password, database, cursorclass=pymysql.cursors.DictCursor)`, run queries with `%s` placeholders and a tuple of values through `cursor.execute`, then call `connection.commit()`, because the connection is not autocommit by default. With DictCursor a fetched row is a dictionary keyed by column name.
What does the "pymysql module not found" error mean and how can I troubleshoot it?
The distribution is named PyMySQL while the module is named pymysql, so the error almost always means the package is missing from the interpreter running your code rather than a wrong import name. Install it with `python3 -m pip install PyMySQL`, using the same interpreter you run the script with, then `import pymysql`.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/pymysql-pymysql)Star history chart for your README
[](https://hysenlabs.com/projects/pymysql-pymysql)Was this useful?