Convex

The official Python client for Convex.

PyPI GitHub

Write and read data from a Convex backend with queries, mutations, and actions. Get up and running at docs.convex.dev.

Installation:

pip install convex

Basic usage:

>>> from convex import ConvexClient
>>> client = ConvexClient('https://example-lion-123.convex.cloud')
>>> messages = client.query("messages:list")
>>> from pprint import pprint
>>> pprint(messages)
[{'_creationTime': 1668107495676.2854,
  '_id': '2sh2c7pn6nyvkexbdsfj66vd9h5q3hg',
  'author': 'Tom',
  'body': 'Have you tried Convex?'},
 {'_creationTime': 1668107497732.2295,
  '_id': '1f053fgh2tt2fc93mw3sn2x09h5bj08',
  'author': 'Sarah',
  'body': "Yeah, it's working pretty well for me."}]
>>> client.mutation("messages:send", dict(author="Me", body="Hello!"))
>>> for messages in client.subscribe("messages:list", {}):
...     print(len(messages))
...
3
<this for loop lasts until you break out with ctrl-c>

To find the url of your convex backend, open the deployment you want to work with in the appropriate project in the Convex dashboard and click "Settings" where the Deployment URL should be visible. To find out which queries, mutations, and actions are available check the Functions pane in the dashboard.

To see logs emitted from Convex functions, set the debug mode to True.

>>> client.set_debug(True)

To provide authentication for function execution, call set_auth().

>>> client.set_auth("token-from-authetication-flow")

To authenticate as an admin, allowing you to run internal functions not exposed to the public internet, call set_admin_auth().

>>> client.set_admin_auth("admin-key")

Join us on Discord to get your questions answered or share what you're doing with Convex. If you're just getting started, see https://docs.convex.dev to see how to quickly spin up a backend that does everything you need in the Convex cloud.

Convex types

Convex backend functions are written in JavaScript, so arguments passed to Convex RPC functions in Python are serialized, sent over the network, and deserialized into JavaScript objects. To learn about Convex's supported types see https://docs.convex.dev/using/types.

In order to call a function that expects a JavaScript type, use the corresponding Python type or any other type that coerces to it. Values returned from Convex will be of the corresponding Python type.

JavaScript Type	Python Type	Example	Other Python Types that Convert
null	None	`None`
bigint	ConvexInt64 (see below)	`ConvexInt64(2**60)`
number	float or int	`3.1`, `10`
boolean	bool	`True`, `False`
string	str	`'abc'`
ArrayBuffer	bytes	`b'abc'`	ArrayBuffer
Array	list	`[1, 3.2, "abc"]`	tuple, collections.abc.Sequence
object	dict	`{a: "abc"}`	collections.abc.Mapping

Ints and Floats

While Convex supports storing Int64s and Float64s, idiomatic JavaScript pervasively uses the (floating point) Number type. In Python floats are often understood to contain the ints: the float type annotation is generally understood as Union[int, float].

Therefore, the Python Convex client converts Python's floats and ints to a Float64 in Convex.

To specify a JavaScript BigInt, use the ConvexInt64 class. Functions which return JavaScript BigInts will return ConvexInt64 instances.

Convex Errors

The Python client supports the ConvexError type to hold application errors that are propagated from your Convex functions. To learn about how to throw ConvexErrors see https://docs.convex.dev/functions/error-handling/application-errors.

On the Python client, ConvexErrors are Exceptions with a data field that contains some ConvexValue. Handling application errors from the Python client might look something like this:

import convex
client = convex.ConvexClient('https://happy-animal-123.convex.cloud')

try:
    client.mutation("messages:sendMessage", {body: "hi", author: "anjan"})
except convex.ConvexError as err:
    if isinstance(err.data, dict):
        if "code" in err.data and err.data["code"] == 1:
            # do something
        else:
            # do something else
    elif isinstance(err.data, str):
        print(err.data)
except Exception as err:
    # log internally

Pagination

Paginated queries are queries that accept pagination options as an argument and can be called repeatedly to produce additional "pages" of results.

For a paginated query like this:

import { query } from "./_generated/server";

export default query({
  handler: async ({ db }, { paginationOpts }) => {
    return await db.query("messages").order("desc").paginate(paginationOpts);
  },
});

and returning all results 5 at a time in Python looks like this:

import convex
client = convex.ConvexClient('https://happy-animal-123.convex.cloud')

done = False
cursor = None
data = []

while not done:
    result = client.query('listMessages', {"paginationOpts": {"numItems": 5, "cursor": cursor}})
    cursor = result['continueCursor']
    done = result["isDone"]
    data.extend(result['page'])
    print('got', len(result['page']), 'results')

print('collected', len(data), 'results')

Versioning

While we are pre-1.0.0, we'll update the minor version for large changes, and the patch version for small bugfixes. We may make backwards incompatible changes to the python client's API, but we will limit those to minor version bumps.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

convex-0.8.1.tar.gz (76.3 kB view details)

Uploaded Sep 14, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

convex-0.8.1-cp314-cp314t-musllinux_1_2_x86_64.whl (4.1 MB view details)

Uploaded Sep 14, 2026 CPython 3.14tmusllinux: musl 1.2+ x86-64

convex-0.8.1-cp314-cp314t-musllinux_1_2_i686.whl (4.1 MB view details)

Uploaded Sep 14, 2026 CPython 3.14tmusllinux: musl 1.2+ i686

convex-0.8.1-cp314-cp314t-musllinux_1_2_armv7l.whl (3.7 MB view details)

Uploaded Sep 14, 2026 CPython 3.14tmusllinux: musl 1.2+ ARMv7l

convex-0.8.1-cp314-cp314t-musllinux_1_2_aarch64.whl (4.5 MB view details)

Uploaded Sep 14, 2026 CPython 3.14tmusllinux: musl 1.2+ ARM64

convex-0.8.1-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.8 MB view details)

Uploaded Sep 14, 2026 CPython 3.14tmanylinux: glibc 2.17+ x86-64

convex-0.8.1-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl (3.7 MB view details)

Uploaded Sep 14, 2026 CPython 3.14tmanylinux: glibc 2.17+ s390x

convex-0.8.1-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl (4.0 MB view details)

Uploaded Sep 14, 2026 CPython 3.14tmanylinux: glibc 2.17+ ppc64le

convex-0.8.1-cp314-cp314t-manylinux_2_17_i686.manylinux2014_i686.whl (4.0 MB view details)

Uploaded Sep 14, 2026 CPython 3.14tmanylinux: glibc 2.17+ i686

convex-0.8.1-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl (3.4 MB view details)

Uploaded Sep 14, 2026 CPython 3.14tmanylinux: glibc 2.17+ ARMv7l

convex-0.8.1-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (4.0 MB view details)

Uploaded Sep 14, 2026 CPython 3.14tmanylinux: glibc 2.17+ ARM64

convex-0.8.1-cp314-cp314t-macosx_11_0_arm64.whl (1.4 MB view details)

Uploaded Sep 14, 2026 CPython 3.14tmacOS 11.0+ ARM64

convex-0.8.1-cp314-cp314t-macosx_10_12_x86_64.whl (1.4 MB view details)

Uploaded Sep 14, 2026 CPython 3.14tmacOS 10.12+ x86-64

convex-0.8.1-cp39-abi3-win_arm64.whl (1.2 MB view details)

Uploaded Sep 14, 2026 CPython 3.9+Windows ARM64

convex-0.8.1-cp39-abi3-win_amd64.whl (1.3 MB view details)

Uploaded Sep 14, 2026 CPython 3.9+Windows x86-64

convex-0.8.1-cp39-abi3-win32.whl (1.2 MB view details)

Uploaded Sep 14, 2026 CPython 3.9+Windows x86

convex-0.8.1-cp39-abi3-musllinux_1_2_x86_64.whl (4.1 MB view details)

Uploaded Sep 14, 2026 CPython 3.9+musllinux: musl 1.2+ x86-64

convex-0.8.1-cp39-abi3-musllinux_1_2_i686.whl (4.1 MB view details)

Uploaded Sep 14, 2026 CPython 3.9+musllinux: musl 1.2+ i686

convex-0.8.1-cp39-abi3-musllinux_1_2_armv7l.whl (3.7 MB view details)

Uploaded Sep 14, 2026 CPython 3.9+musllinux: musl 1.2+ ARMv7l

convex-0.8.1-cp39-abi3-musllinux_1_2_aarch64.whl (4.5 MB view details)

Uploaded Sep 14, 2026 CPython 3.9+musllinux: musl 1.2+ ARM64

convex-0.8.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.9 MB view details)

Uploaded Sep 14, 2026 CPython 3.9+manylinux: glibc 2.17+ x86-64

convex-0.8.1-cp39-abi3-manylinux_2_17_s390x.manylinux2014_s390x.whl (3.7 MB view details)

Uploaded Sep 14, 2026 CPython 3.9+manylinux: glibc 2.17+ s390x

convex-0.8.1-cp39-abi3-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl (4.0 MB view details)

Uploaded Sep 14, 2026 CPython 3.9+manylinux: glibc 2.17+ ppc64le

convex-0.8.1-cp39-abi3-manylinux_2_17_i686.manylinux2014_i686.whl (4.0 MB view details)

Uploaded Sep 14, 2026 CPython 3.9+manylinux: glibc 2.17+ i686

convex-0.8.1-cp39-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl (3.4 MB view details)

Uploaded Sep 14, 2026 CPython 3.9+manylinux: glibc 2.17+ ARMv7l

convex-0.8.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (4.1 MB view details)

Uploaded Sep 14, 2026 CPython 3.9+manylinux: glibc 2.17+ ARM64

convex-0.8.1-cp39-abi3-macosx_11_0_arm64.whl (1.4 MB view details)

Uploaded Sep 14, 2026 CPython 3.9+macOS 11.0+ ARM64

convex-0.8.1-cp39-abi3-macosx_10_12_x86_64.whl (1.4 MB view details)

Uploaded Sep 14, 2026 CPython 3.9+macOS 10.12+ x86-64

File details

Details for the file convex-0.8.1.tar.gz.

File metadata

Download URL: convex-0.8.1.tar.gz
Upload date: Sep 14, 2026
Size: 76.3 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: maturin/1.15.0

File hashes

Hashes for convex-0.8.1.tar.gz
Algorithm	Hash digest
SHA256	`79aab5f5412a2e0bb4b3f790c1019d437a907987fda5e338d14589dbaca47fb9`
MD5	`0b6188a5a432622833a6444082eae820`
BLAKE2b-256	`b252a90690bd3af2ef0534e4f1855eafbd4a0fbd8692ad6ef96e833e1570a65e`

Algorithm	Hash digest
SHA256	`9a11e20e52655ce597f7e738aaafe61c307aed6d350a1f20e8fdee0174df03ad`
MD5	`f26543d3a81d43fbb838f583d37dfabb`
BLAKE2b-256	`426b5a528eb8bf5d038a8162c8a61cdba581a7a2ce33e59ed0bbb9e9f542c8fa`

Algorithm	Hash digest
SHA256	`53efda83232fd4b86b007451b87b3688a767aea510e0f6455b4916fae1a61202`
MD5	`99abccc34c2dbea2f08c456b2b7e1aa2`
BLAKE2b-256	`7a9f2547d3ea92d18eae26c7430e8623f378d27a48c20363e47b5e7c2cff85eb`

Algorithm	Hash digest
SHA256	`6d3272884e8a33b85c2c04871bf5d57ee0e1980fe166304bf919fe47f0d092d4`
MD5	`85e49c8ee0b1ccbcf39ca729666f88ac`
BLAKE2b-256	`92ed672bd291732ced9a4739a983644e096e3af63279913ea890528f2e326feb`

Algorithm	Hash digest
SHA256	`0be5dd152f6eaf3b81406fae012975d12b388767ade562adc119682634b54706`
MD5	`9f040dd1ead688c1a659036c5a9dd76d`
BLAKE2b-256	`20965fd1f8a98f6b0319eab66b9fad9880a0ee3ff09675d57d1e498b165e9cfa`

Algorithm	Hash digest
SHA256	`7885ed039cabadd76444aec9253b85b47c67665499f3f1cf9748f3631ce0cb9b`
MD5	`0d79f0799a9869f12a5f4ed29274b515`
BLAKE2b-256	`3df397476aa70a6fb308103073407fe88b99bd078711fa5d7f06db17b6c00eaf`

Algorithm	Hash digest
SHA256	`7859a22ce48dd75287b7ae107925baf482de9bc1b2fef8d91b6de8c4e367cf8f`
MD5	`8960afcf132e66780435ad6c0e15324b`
BLAKE2b-256	`91eb5bd49d72cad03e2e2c5162d398c37924d2da6de5c28c572577ce38771047`

Algorithm	Hash digest
SHA256	`9daa247c748a796ef8d2001a3602335314d43bd04483e844a6083a612646afde`
MD5	`f833c9e5a40b1d8a502250c12033d2b5`
BLAKE2b-256	`b13482470c6ad2364df45f6cc1e94f0672b423fc126791fa99b385bcaf0d5457`

Algorithm	Hash digest
SHA256	`8c2561ef6f99848929d90036586b5699fa37ddce620da019edc0e6b82dfe2e81`
MD5	`7e8bdf7ffa26c219fb391c9d67a54423`
BLAKE2b-256	`448038a74aa2ebfbbf300aef5f37a9f96fb00bbb2601a85a6a547a18e977bf26`

Algorithm	Hash digest
SHA256	`1f5b5bc9dbeaaca4d6e72c2153563ce408d9a19790339696a291ee66786f6943`
MD5	`8731bd08baf07a09c030818c176e2802`
BLAKE2b-256	`62a509eab6d612df5cdb2f133d3ff7e8b0b80aafb9a6483f24c79b464c3ce605`

Algorithm	Hash digest
SHA256	`261c45b08b443951172dba88f7569dc9e63b6710751dc5bbeaa289c2c657d237`
MD5	`75aa20b8508423f564676224135ae8ab`
BLAKE2b-256	`2cd589c972bc12443059f800e5fcc9bbb376a43ef11520a84701ffa8d05ce3fe`

Algorithm	Hash digest
SHA256	`cea740862809ac575a0af6cd7c1288de78c1ec29fdce96c53fbf96ca88c136ca`
MD5	`2694f863d0700389a283599685f58e97`
BLAKE2b-256	`4740d5ac9e4cb607ad780c622cb4bbf70c99c676ba5e76ac5ae57cc034e640b5`

Algorithm	Hash digest
SHA256	`96745432a82e9219f93ac8d0864756756596444f73880f211d158527e1139eda`
MD5	`25cf6954143490ed57d0fd38c13b92ca`
BLAKE2b-256	`b68c51b3387fadb54613b3a860feb9e4a3a50299c260891b2873d2050ff2f0ed`

Algorithm	Hash digest
SHA256	`1f7e563dd9cc873353d670eb8f276c15af9acda8eb42b8b3f6233b856a6197e3`
MD5	`523029cc1ba239d8e0577dfe73ebefff`
BLAKE2b-256	`005ce3e77775dc87a209ba92f983f3adf0430cea4a876ff2003ce3129d036a40`

Algorithm	Hash digest
SHA256	`097f0d421df91fb9147baaa99ecfc52651bcd7e777dc0ffd187f69eb818bd87e`
MD5	`bf350bddf27fd7796c18f02c754ce8b6`
BLAKE2b-256	`893fb023cdd4375dc6151ee60b83c6da7a10b8bc9249ddbd53d0867cad3a147c`

Algorithm	Hash digest
SHA256	`5d77f457a01a3cf21be8a4809595050462f6707984892a21c2abec30524dfe76`
MD5	`6ae8cc29bcacac2eeaf47a848a5cda76`
BLAKE2b-256	`8345c7fb3834990b6b6f75d7501f4c384977b9eb9be96ef2024746d6a2e463ff`

Algorithm	Hash digest
SHA256	`4a88da044687bc91ecfc7fbae709f278b409e248bac44a8a67775ad2e6fd2f94`
MD5	`5774098934636b7723c342bee049e0a2`
BLAKE2b-256	`2ee2f17cedd6dfe377de66aca14327bf44e183d388ad691d1c3dde95ccacb1cb`

Algorithm	Hash digest
SHA256	`ace579487f292027f41bc469b039f0b7bb075fcf8cc0015202dc2b394a441fd7`
MD5	`df0232273bf123aeb477221d0df77a86`
BLAKE2b-256	`1d9efc9503977f0ca0d2ac057a89b5b9c256c7914d4a2c7b75d717acf6e51f76`

Algorithm	Hash digest
SHA256	`74a3756efe45452f39df2a1aa22ac968d5a915892b607819a044af8d358d47d2`
MD5	`3306d3b0042d44ef2d5deaaba51afa8f`
BLAKE2b-256	`cdcc012616f76a91ead99664cb7e320092f4df5dc9eba77fa3b1c61185a6f4d1`

Algorithm	Hash digest
SHA256	`b62e87d064900331f5f6936c4e1763c2c93fe4adaeea3a028fb70d4c239644a5`
MD5	`ba3e9754246292a983bdb16c33162c3c`
BLAKE2b-256	`b488f51cbf8beb6dfb4f0098e94a65a9de1a18d6ba2e5b2607d300b3deaf64c5`

Algorithm	Hash digest
SHA256	`82e77d1a977e6329fc4804a3ec0af063eb2e58dd4aafb9c091d65dae4524942a`
MD5	`df62faf96dabe10725d3ac04dfebc107`
BLAKE2b-256	`ce79e5deedc8f415ef0a3daac8f1d6c50869fe956a14ce2d46e0caaa8ae9aece`

convex 0.8.1

Convex

Convex types

Ints and Floats

Convex Errors

Pagination

Versioning

Project links

Key dates

3 maintainers

Credits

GitHub Statistics

Requires

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

Algorithm	Hash digest
SHA256	`07902a28de8db09d18fbd56633043f9a837a6eb51d69930d275a0e1f422c529f`
MD5	`64bf87415539d0b8b2a59b679429e471`
BLAKE2b-256	`cc21068c611c362e43eae5c4cf40dfc84e98f5ee4f539366d75fa048e1d623f8`

Algorithm	Hash digest
SHA256	`c2d05ca20259cdeb42eda578575436417e31bacab6c765d3e2d83bb3126f98fe`
MD5	`1a574df8834a4534986ee66e501b3e37`
BLAKE2b-256	`9c237b55f0a81a7030a1c53a9b3e96f837a6e10e1d2fed311034ee4fa1bab958`

Algorithm	Hash digest
SHA256	`fda0d56295f42849047daf0db027a279d394964706f53df20f9650a06a976955`
MD5	`1baaed75adef88a31ba444c778f50d80`
BLAKE2b-256	`82f9c3447750ce57992cfe114257633f4f3ce6389d2592febf215642c5e1d717`

Algorithm	Hash digest
SHA256	`9a7896132a5bf99e73c9a0eeed1fe74f3cd5793bbfb90d9496d3e8de5a1ddee3`
MD5	`5eec841ba95ac9f438712f94d2d06ab6`
BLAKE2b-256	`b7af561c806e3b61858bfa085f70878182157b5e61f35d04bb28eed1f13eeb78`

Algorithm	Hash digest
SHA256	`e464b52171bb1ce7663eb97c7fa1d63b3cee2393c65940a2a2e3a7c9df7b4fa2`
MD5	`8fa3829bba868a32a96e697731253252`
BLAKE2b-256	`e75857527b45321005701a2d61e22eb40dcf3119b5a5abf762adc62c24128dde`

Algorithm	Hash digest
SHA256	`55c7972a9fe33c8183e15ab94793eb65bb31f3bb5fb98b0351c152a35754e92f`
MD5	`0cc6021dd2fd552606da62c9b1e4787e`
BLAKE2b-256	`f788adf1380870b01f9e6a5950ada6b68b4e5d816fb69a85542ed058333b7044`

Algorithm	Hash digest
SHA256	`31a8a6f7f97fe5edc823eb49484f9b2a6d0da4f0b2b30bc69e345fb4add5bb41`
MD5	`7c721b7d688a9148d3880889221a2338`
BLAKE2b-256	`39a115f78733053c02ae4eb447ee239b742413e3565d549b9999cfc5cce7005d`