1.. _install: 2 3PycURL Installation 4=================== 5 6NOTE: You need Python and libcurl installed on your system to use or 7build pycurl. Some RPM distributions of curl/libcurl do not include 8everything necessary to build pycurl, in which case you need to 9install the developer specific RPM which is usually called curl-dev. 10 11 12Distutils 13--------- 14 15Build and install pycurl with the following commands:: 16 17 (if necessary, become root) 18 tar -zxvf pycurl-$VER.tar.gz 19 cd pycurl-$VER 20 python setup.py install 21 22$VER should be substituted with the pycurl version number, e.g. 7.10.5. 23 24Note that the installation script assumes that 'curl-config' can be 25located in your path setting. If curl-config is installed outside 26your path or you want to force installation to use a particular 27version of curl-config, use the '--curl-config' command line option to 28specify the location of curl-config. Example:: 29 30 python setup.py install --curl-config=/usr/local/bin/curl-config 31 32If libcurl is linked dynamically with pycurl, you may have to alter the 33LD_LIBRARY_PATH environment variable accordingly. This normally 34applies only if there is more than one version of libcurl installed, 35e.g. one in /usr/lib and one in /usr/local/lib. 36 37 38SSL 39^^^ 40 41PycURL requires that the SSL library that it is built against is the same 42one libcurl, and therefore PycURL, uses at runtime. PycURL's ``setup.py`` 43uses ``curl-config`` to attempt to figure out which SSL library libcurl 44was compiled against, however this does not always work. If PycURL is unable 45to determine the SSL library in use it will print a warning similar to 46the following:: 47 48 src/pycurl.c:137:4: warning: #warning "libcurl was compiled with SSL support, but configure could not determine which " "library was used; thus no SSL crypto locking callbacks will be set, which may " "cause random crashes on SSL requests" [-Wcpp] 49 50It will then fail at runtime as follows:: 51 52 ImportError: pycurl: libcurl link-time ssl backend (openssl) is different from compile-time ssl backend (none/other) 53 54To fix this, you need to tell ``setup.py`` what SSL backend is used:: 55 56 python setup.py --with-[openssl|gnutls|nss|mbedtls|wolfssl] install 57 58Note: as of PycURL 7.21.5, setup.py accepts ``--with-openssl`` option to 59indicate that libcurl is built against OpenSSL/LibreSSL/BoringSSL. 60``--with-ssl`` is an alias 61for ``--with-openssl`` and continues to be accepted for backwards compatibility. 62 63You can also ask ``setup.py`` to obtain SSL backend information from installed 64libcurl shared library, as follows: 65 66 python setup.py --libcurl-dll=libcurl.so 67 68An unqualified ``libcurl.so`` would use the system libcurl, or you can 69specify a full path. 70 71 72easy_install / pip 73------------------ 74 75:: 76 77 easy_install pycurl 78 pip install pycurl 79 80If you need to specify an alternate curl-config, it can be done via an 81environment variable:: 82 83 export PYCURL_CURL_CONFIG=/usr/local/bin/curl-config 84 easy_install pycurl 85 86The same applies to the SSL backend, if you need to specify it (see the SSL 87note above):: 88 89 export PYCURL_SSL_LIBRARY=[openssl|gnutls|nss|mbedtls] 90 easy_install pycurl 91 92 93pip and cached pycurl package 94^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 95 96If you have already installed pycurl and are trying to reinstall it via 97pip with different SSL options for example, pip may reinstall the package it 98has previously compiled instead of recompiling pycurl with newly specified 99options. More details are given in `this Stack Overflow post`_. 100 101To force pip to recompile pycurl, run:: 102 103 # upgrade pip if necessary 104 pip install --upgrade pip 105 106 # remove current pycurl 107 pip uninstall pycurl 108 109 # set PYCURL_SSL_LIBRARY 110 export PYCURL_SSL_LIBRARY=nss 111 112 # recompile and install pycurl 113 pip install --compile pycurl 114 115.. _this Stack Overflow post: http://stackoverflow.com/questions/21487278/ssl-error-installing-pycurl-after-ssl-is-set 116 117 118Windows 119------- 120 121There are currently no official binary Windows packages. You can build PycURL 122from source or use third-party binary packages. 123 124 125Building From Source 126^^^^^^^^^^^^^^^^^^^^ 127 128Building PycURL from source is not for the faint of heart due to the multitude 129of possible dependencies and each of these dependencies having its own 130directory structure, configuration style, parameters and quirks. 131Additionally different dependencies have different 132settings for MSVCRT usage, and an application must have all of its parts 133agreeing on a single setting. If you decide to build PycURL from source 134it is advisable to look through the ``winbuild.py`` 135script - it is used to build the official binaries and contains a wealth 136of information for compiling PycURL's dependencies on Windows. 137 138If you are compiling PycURL from source it is recommended to compile all of its 139dependencies from source as well. Using precompiled libraries may lead to 140multiple MSVCRT versions mixed in the resulting PycURL binary, which will 141not be good. 142 143If PycURL is to be linked statically against its dependencies, OpenSSL must 144be patched to link to the DLL version of MSVCRT. There is a patch for this in 145``winbuild`` directory of PycURL source. 146 147For a minimum build you will just need libcurl source. Follow its Windows 148build instructions to build either a static or a DLL version of the library, 149then configure PycURL as follows to use it:: 150 151 python setup.py --curl-dir=c:\dev\curl-7.33.0\builds\libcurl-vc-x86-release-dll-ipv6-sspi-spnego-winssl --use-libcurl-dll 152 153Note that ``--curl-dir`` must point not to libcurl source but rather to headers 154and compiled libraries. 155 156If libcurl and Python are not linked against the same exact C runtime 157(version number, static/dll, single-threaded/multi-threaded) you must use 158``--avoid-stdio`` option (see below). 159 160Additional Windows setup.py options: 161 162- ``--use-libcurl-dll``: build against libcurl DLL, if not given PycURL will 163 be built against libcurl statically. 164- ``--libcurl-lib-name=libcurl_imp.lib``: specify a different name for libcurl 165 import library. The default is ``libcurl.lib`` which is appropriate for 166 static linking and is sometimes the correct choice for dynamic linking as 167 well. The other possibility for dynamic linking is ``libcurl_imp.lib``. 168- ``--with-openssl``: use OpenSSL/LibreSSL/BoringSSL crypto locks when libcurl 169 was built against these SSL backends. 170- ``--with-ssl``: legacy alias for ``--with-openssl``. 171- ``--openssl-lib-name=""``: specify a different name for OpenSSL import 172 library containing CRYPTO_num_locks. For OpenSSL 1.1.0+ this should be set 173 to an empty string as given here. 174- ``--avoid-stdio``: on Windows, a process and each library it is using 175 may be linked to its own version of the C runtime (MSVCRT). 176 FILE pointers from one C runtime may not be passed to another C runtime. 177 This option prevents direct passing of FILE pointers from Python to libcurl, 178 thus permitting Python and libcurl to be linked against different C runtimes. 179 This option may carry a performance penalty when Python file objects are 180 given directly to PycURL in CURLOPT_READDATA, CURLOPT_WRITEDATA or 181 CURLOPT_WRITEHEADER options. This option applies only on Python 2; on 182 Python 3, file objects no longer expose C library FILE pointers and the 183 C runtime issue does not exist. On Python 3, this option is recognized but 184 does nothing. You can also give ``--avoid-stdio`` option in 185 PYCURL_SETUP_OPTIONS environment variable as follows:: 186 187 PYCURL_SETUP_OPTIONS=--avoid-stdio pip install pycurl 188 189A good ``setup.py`` target to use is ``bdist_wininst`` which produces an 190executable installer that you can run to install PycURL. 191 192You may find the following mailing list posts helpful: 193 194- https://curl.haxx.se/mail/curlpython-2009-11/0010.html 195- https://curl.haxx.se/mail/curlpython-2013-11/0002.html 196 197 198winbuild.py 199^^^^^^^^^^^ 200 201This script is used to build official PycURL Windows packages. You can 202use it to build a full complement of packages with your own options or modify 203it to build a single package you need. 204 205Prerequisites: 206 207- `Git for Windows`_. 208- Appropriate `Python versions`_ installed. 209- MS Visual C++ 9/2008 for Python <= 3.2, MS Visual C++ 10/2010 for 210 Python 3.3 or 3.4, MS Visual C++ 14/2015 for Python 3.5 through 3.8. 211 Express versions of Visual Studio work fine for this, 212 although getting 64 bit compilers to wok in some Express versions involves 213 jumping through several hoops. 214- NASM if building libcurl against OpenSSL. 215- ActivePerl if building libcurl against OpenSSL. The perl shipping with 216 Git for Windows handles forward and backslashes in paths in a way that is 217 incompatible with OpenSSL's build scripts. 218 219.. _Git for Windows: https://git-for-windows.github.io/ 220.. _Python versions: http://python.org/download/ 221 222``winbuild.py`` assumes all programs are installed in their default locations, 223if this is not the case edit it as needed. ``winbuild.py`` itself can be run 224with any Python it supports. 225 226 227Using PycURL With Custom Python Builds 228^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 229 230As of version 7.21.5, the official binary packages of PycURL are linked 231statically against all of its dependencies except MSVCRT. This means that 232as long as your custom Python build uses the same version of MSVC as the 233corresponding official Python build as well as the same MSVCRT linking setting 234(/MD et. al.), an official PycURL package should work. 235 236If your Python build uses different MSVCRT settings or a different MSVC 237version from the official Python builds, you will need to compile PycURL 238from source. 239 240If the C runtime library (MSVCRT.DLL) versions used by PycURL and Python 241do not match, you will receive a message 242like the following one when trying to import ``pycurl`` module:: 243 244 ImportError: DLL load failed: The specified procedure could not be found. 245 246To identify which MSVCRT version your Python uses use the 247`application profiling feature`_ of 248`Dependency Walker`_ and look for `msvcrt.dll variants`_ being loaded. 249You may find `the entire thread starting here`_ helpful. 250 251.. _application profiling feature: https://curl.haxx.se/mail/curlpython-2014-05/0007.html 252.. _Dependency Walker: http://www.dependencywalker.com/ 253.. _msvcrt.dll variants: https://curl.haxx.se/mail/curlpython-2014-05/0010.html 254.. _the entire thread starting here: https://curl.haxx.se/mail/curlpython-2014-05/0000.html 255 256 257Git Checkout 258------------ 259 260In order to build PycURL from a Git checkout, some files need to be 261generated. On Unix systems it is easiest to build PycURL with ``make``:: 262 263 make 264 265To specify which curl or SSL backend to compile against, use the same 266environment variables as easy_install/pip, namely ``PYCURL_CURL_CONFIG`` 267and ``PYCURL_SSL_LIBRARY``. 268 269To generate generated files only you may run:: 270 271 make gen 272 273This might be handy if you are on Windows. Remember to run ``make gen`` 274whenever you change sources. 275 276To generate documentation, run:: 277 278 make docs 279 280Generating documentation requires `Sphinx`_ to be installed. 281 282.. _Sphinx: http://sphinx-doc.org/ 283 284 285A Note Regarding SSL Backends 286----------------------------- 287 288libcurl's functionality varies depending on which SSL backend it is compiled 289against. For example, users have `reported`_ `problems`_ with GnuTLS backend. 290As of this writing, generally speaking, OpenSSL backend has the most 291functionality as well as the best compatibility with other software. 292 293If you experience SSL issues, especially if you are not using OpenSSL 294backend, you can try rebuilding libcurl and PycURL against another SSL backend. 295 296.. _reported: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=515200 297.. _problems: https://bugs.launchpad.net/ubuntu/+source/pycurl/+bug/1111673 298 299 300SSL Certificate Bundle 301---------------------- 302 303libcurl, and PycURL, by default verify validity of HTTPS servers' SSL 304certificates. Doing so requires a CA certificate bundle, which libcurl 305and most SSL libraries do not provide. 306 307Here_ is a good resource on how to build your own certificate bundle. 308certifie.com also has a `prebuilt certificate bundle`_. 309To use the certificate bundle, use ``CAINFO`` or ``CAPATH`` PycURL 310options. 311 312.. _Here: http://certifie.com/ca-bundle/ 313.. _prebuilt certificate bundle: http://certifie.com/ca-bundle/ca-bundle.crt.txt 314