Install & Compatibility
Where this runs
tested against v7.47.0.20260703 · 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
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.038s · 32MB
30MB installed
● package 30MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Curl
✓ import pycurl
from io import BytesIO
c = pycurl.Curl()
pycurl.error
✓ import pycurl
try:
# pycurl operations
pass
except pycurl.error as e:
print(f"PycURL error: {e}")
This quickstart demonstrates how to make a basic HTTPS GET request using pycurl, capture the response body into a BytesIO object, and handle potential errors. It includes the recommended practice of using the `certifi` package to specify an up-to-date CA certificate bundle for secure connections. The `types-pycurl` package, when installed, provides type checking for `pycurl` usage in this code.
import pycurl
from io import BytesIO
import certifi
import os
buffer = BytesIO()
c = pycurl.Curl()
# Set the URL and write data to the buffer
c.setopt(pycurl.URL, 'https://example.com')
c.setopt(pycurl.WRITEDATA, buffer)
# Configure SSL certificates using certifi for secure connections
# (optional, but recommended for HTTPS)
if os.environ.get('PYCURL_CA_BUNDLE_PATH'):
c.setopt(pycurl.CAINFO, os.environ.get('PYCURL_CA_BUNDLE_PATH'))
elif os.path.exists(certifi.where()):
c.setopt(pycurl.CAINFO, certifi.where())
try:
c.perform()
body = buffer.getvalue().decode('utf-8')
print(f"HTTP Status Code: {c.getinfo(pycurl.HTTP_CODE)}")
print(f"Response body length: {len(body)} characters")
# print(body[:500]) # Print first 500 characters of the body
except pycurl.error as e:
# Troubleshooting tip: Enable verbose logging for more details
# c.setopt(pycurl.VERBOSE, True)
print(f"An error occurred: {e}")
finally:
c.close()
Debug
Known issues
gotchaPycURL expects byte strings for non-ASCII data in many options (e.g., URL, POSTFIELDS). Passing Unicode strings with non-ASCII characters directly can lead to `UnicodeEncodeError` or `pycurl.error` (e.g., 'read function error/data error') if PycURL cannot encode them to ASCII.fixExplicitly encode Unicode strings to bytes (e.g., `.encode('utf-8')`) before passing them to pycurl methods or options that expect binary data. affects: All Python 3 versions of pycurl
gotchaWhen `pycurl` encounters an error from the underlying `libcurl` library, it raises `pycurl.error`. The exception message may contain a numeric error code from `libcurl` (e.g., `(1, '')` for `CURLE_UNSUPPORTED_PROTOCOL`). The generic message might not immediately indicate the root cause.fixFor detailed debugging, set `c.setopt(pycurl.VERBOSE, True)` before `c.perform()`. This will print extensive `libcurl` debugging information to stderr, which can help diagnose connection, SSL, or protocol-related issues.
affects: All versions
gotchaPassing an argument of an incorrect type to `c.setopt()` (e.g., an integer where a string is expected) will raise a `TypeError: invalid arguments to setopt`. Carefully check the `libcurl` documentation for the expected argument type of each option.fixConsult the PycURL documentation or `libcurl`'s `curl_easy_setopt` page for the specific option to ensure the correct Python type is used (e.g., `str` vs. `bytes`, `int`, `list`, `tuple`).
affects: All versions
breakingThe `DEBUGFUNCTION` callback on Python 3 changed to take `bytes` rather than (Unicode) `str` as its argument. Code expecting `str` will need to decode the input.fixEnsure `DEBUGFUNCTION` callbacks are prepared to handle `bytes` objects on Python 3 by decoding them if string manipulation is required (e.g., `data.decode('utf-8')`). affects: PycURL versions < 7.19.0 (introduced in 7.19.0)
gotchaOn Windows, an `ImportError` related to `libcurl` or `OpenSSL` can occur if the compile-time and runtime SSL backends do not match, or if `OpenSSL` headers are missing.fixEnsure OpenSSL is correctly installed on your system. For `pycurl` builds, it might be necessary to specify the SSL backend to `setup.py` (e.g., `--with-openssl`) or set environment variables like `PYCURL_SSL_LIBRARY` on Windows to point to your OpenSSL installation. Refer to `pycurl`'s installation documentation for platform-specific details.
affects: All versions on Windows
Upgrade
Version history
7.47.0.20260703latest on PyPI · released Jul 3, 2026
Audit
Dependencies
pycurlrequiredThis package provides type stubs for the runtime library `pycurl`.
certifioptionalCommonly used with pycurl for up-to-date SSL certificate bundles, especially for HTTPS requests.