1<!doctype html> 2<html class="no-js" lang="en" data-content_root="../"> 3 <head><meta charset="utf-8"> 4 <meta name="viewport" content="width=device-width,initial-scale=1"> 5 <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" /> 6<link rel="index" title="Index" href="../genindex.html"><link rel="search" title="Search" href="../search.html"><link rel="next" title="Basic module usage" href="usage.html"><link rel="prev" title="Getting started with Psycopg 3" href="index.html"> 7 <link rel="prefetch" href="../_static/psycopg.png" as="image"> 8 <link rel="prefetch" href="../_static/psycopg.png" as="image"> 9 10 <!-- Generated with Sphinx 9.1.0 and Furo 2025.12.19 --> 11 <title>Installation - psycopg 3.3.7.dev1 documentation</title> 12 <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=8f2a1f02" /> 13 <link rel="stylesheet" type="text/css" href="../_static/styles/furo.css?v=7bdb33bb" /> 14 <link rel="stylesheet" type="text/css" href="../_static/styles/furo-extensions.css?v=8dab3a3b" /> 15 <link rel="stylesheet" type="text/css" href="../_static/psycopg.css?v=67dada6b" /> 16 17 18 19 20<style> 21 body { 22 --color-code-background: #f8f8f8; 23 --color-code-foreground: black; 24 --admonition-font-size: 1rem; 25 26 } 27 @media not print { 28 body[data-theme="dark"] { 29 --color-code-background: #202020; 30 --color-code-foreground: #d0d0d0; 31 32 } 33 @media (prefers-color-scheme: dark) { 34 body:not([data-theme="light"]) { 35 --color-code-background: #202020; 36 --color-code-foreground: #d0d0d0; 37 38 } 39 } 40 } 41</style></head> 42 <body> 43 44
44<script> 45 document.body.dataset.theme = localStorage.getItem("theme") || "auto"; 46 </script>
46 47 48 49<svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> 50 <symbol id="svg-toc" viewBox="0 0 24 24"> 51 <title>Contents</title> 52 <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024"> 53 <path d="M408 442h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8zm-8 204c0 4.4 3.6 8 8 8h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56zm504-486H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zm0 632H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zM115.4 518.9L271.7 642c5.8 4.6 14.4.5 14.4-6.9V388.9c0-7.4-8.5-11.5-14.4-6.9L115.4 505.1a8.74 8.74 0 0 0 0 13.8z"/> 54 </svg> 55 </symbol> 56 <symbol id="svg-menu" viewBox="0 0 24 24"> 57 <title>Menu</title> 58 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 59 stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-menu"> 60 <line x1="3" y1="12" x2="21" y2="12"></line> 61 <line x1="3" y1="6" x2="21" y2="6"></line> 62 <line x1="3" y1="18" x2="21" y2="18"></line> 63 </svg> 64 </symbol> 65 <symbol id="svg-arrow-right" viewBox="0 0 24 24"> 66 <title>Expand</title> 67 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 68 stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-chevron-right"> 69 <polyline points="9 18 15 12 9 6"></polyline> 70 </svg> 71 </symbol> 72 <symbol id="svg-sun" viewBox="0 0 24 24"> 73 <title>Light mode</title> 74 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 75 stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="feather-sun"> 76 <circle cx="12" cy="12" r="5"></circle> 77 <line x1="12" y1="1" x2="12" y2="3"></line> 78 <line x1="12" y1="21" x2="12" y2="23"></line> 79 <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> 80 <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> 81 <line x1="1" y1="12" x2="3" y2="12"></line> 82 <line x1="21" y1="12" x2="23" y2="12"></line> 83 <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> 84 <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> 85 </svg> 86 </symbol> 87 <symbol id="svg-moon" viewBox="0 0 24 24"> 88 <title>Dark mode</title> 89 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 90 stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon"> 91 <path stroke="none" d="M0 0h24v24H0z" fill="none" /> 92 <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z" /> 93 </svg> 94 </symbol> 95 <symbol id="svg-sun-with-moon" viewBox="0 0 24 24"> 96 <title>Auto light/dark, in light mode</title> 97 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 98 stroke-width="1" stroke-linecap="round" stroke-linejoin="round" 99 class="icon-custom-derived-from-feather-sun-and-tabler-moon"> 100 <path style="opacity: 50%" d="M 5.411 14.504 C 5.471 14.504 5.532 14.504 5.591 14.504 C 3.639 16.319 4.383 19.569 6.931 20.352 C 7.693 20.586 8.512 20.551 9.25 20.252 C 8.023 23.207 4.056 23.725 2.11 21.184 C 0.166 18.642 1.702 14.949 4.874 14.536 C 5.051 14.512 5.231 14.5 5.411 14.5 L 5.411 14.504 Z"/> 101 <line x1="14.5" y1="3.25" x2="14.5" y2="1.25"/> 102 <line x1="14.5" y1="15.85" x2="14.5" y2="17.85"/> 103 <line x1="10.044" y1="5.094" x2="8.63" y2="3.68"/> 104 <line x1="19" y1="14.05" x2="20.414" y2="15.464"/> 105 <line x1="8.2" y1="9.55" x2="6.2" y2="9.55"/> 106 <line x1="20.8" y1="9.55" x2="22.8" y2="9.55"/> 107 <line x1="10.044" y1="14.006" x2="8.63" y2="15.42"/> 108 <line x1="19" y1="5.05" x2="20.414" y2="3.636"/> 109 <circle cx="14.5" cy="9.55" r="3.6"/> 110 </svg> 111 </symbol> 112 <symbol id="svg-moon-with-sun" viewBox="0 0 24 24"> 113 <title>Auto light/dark, in dark mode</title> 114 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 115 stroke-width="1" stroke-linecap="round" stroke-linejoin="round" 116 class="icon-custom-derived-from-feather-sun-and-tabler-moon"> 117 <path d="M 8.282 7.007 C 8.385 7.007 8.494 7.007 8.595 7.007 C 5.18 10.184 6.481 15.869 10.942 17.24 C 12.275 17.648 13.706 17.589 15 17.066 C 12.851 22.236 5.91 23.143 2.505 18.696 C -0.897 14.249 1.791 7.786 7.342 7.063 C 7.652 7.021 7.965 7 8.282 7 L 8.282 7.007 Z"/> 118 <line style="opacity: 50%" x1="18" y1="3.705" x2="18" y2="2.5"/> 119 <line style="opacity: 50%" x1="18" y1="11.295" x2="18" y2="12.5"/> 120 <line style="opacity: 50%" x1="15.316" y1="4.816" x2="14.464" y2="3.964"/> 121 <line style="opacity: 50%" x1="20.711" y1="10.212" x2="21.563" y2="11.063"/> 122 <line style="opacity: 50%" x1="14.205" y1="7.5" x2="13.001" y2="7.5"/> 123 <line style="opacity: 50%" x1="21.795" y1="7.5" x2="23" y2="7.5"/> 124 <line style="opacity: 50%" x1="15.316" y1="10.184" x2="14.464" y2="11.036"/> 125 <line style="opacity: 50%" x1="20.711" y1="4.789" x2="21.563" y2="3.937"/> 126 <circle style="opacity: 50%" cx="18" cy="7.5" r="2.169"/> 127 </svg> 128 </symbol> 129 <symbol id="svg-pencil" viewBox="0 0 24 24"> 130 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 131 stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-pencil-code"> 132 <path d="M4 20h4l10.5 -10.5a2.828 2.828 0 1 0 -4 -4l-10.5 10.5v4" /> 133 <path d="M13.5 6.5l4 4" /> 134 <path d="M20 21l2 -2l-2 -2" /> 135 <path d="M17 17l-2 2l2 2" /> 136 </svg> 137 </symbol> 138 <symbol id="svg-eye" viewBox="0 0 24 24"> 139 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" 140 stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-eye-code"> 141 <path stroke="none" d="M0 0h24v24H0z" fill="none" /> 142 <path d="M10 12a2 2 0 1 0 4 0a2 2 0 0 0 -4 0" /> 143 <path 144 d="M11.11 17.958c-3.209 -.307 -5.91 -2.293 -8.11 -5.958c2.4 -4 5.4 -6 9 -6c3.6 0 6.6 2 9 6c-.21 .352 -.427 .688 -.647 1.008" /> 145 <path d="M20 21l2 -2l-2 -2" /> 146 <path d="M17 17l-2 2l2 2" /> 147 </svg> 148 </symbol> 149</svg> 150 151<input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation" aria-label="Toggle site navigation sidebar"> 152<input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc" aria-label="Toggle table of contents sidebar"> 153<label class="overlay sidebar-overlay" for="__navigation"></label> 154<label class="overlay toc-overlay" for="__toc"></label> 155 156<a class="skip-to-content muted-link" href="#furo-main-content">Skip to content</a> 157 158<div class="announcement"> 159 <aside class="announcement-content"> 160 <a style="text-decoration: none; color: white;" 161 href="https://github.com/sponsors/psycopg/"> 162 <img height="24px" width="24px" src="/img/logo/psycopg-48.png"/> 163 Sponsor Psycopg on GitHub 164</a> 165 166 </aside> 167</div> 168 169<div class="page"> 170 <header class="mobile-header"> 171 <div class="header-left"> 172 <label class="nav-overlay-icon" for="__navigation">
173 <span class="icon"><svg><use href="#svg-menu"></use></svg></span> 174 </label> 175 </div> 176 <div class="header-center"> 177 <a href="../index.html"><div class="brand">psycopg 3.3.7.dev1 documentation</div></a> 178 </div> 179 <div class="header-right"> 180 <div class="theme-toggle-container theme-toggle-header"> 181 <button class="theme-toggle" aria-label="Toggle Light / Dark / Auto color theme"> 182 <svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg> 183 <svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg> 184 <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg> 185 <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg> 186 </button> 187 </div> 188 <label class="toc-overlay-icon toc-header-icon" for="__toc"> 189 <span class="icon"><svg><use href="#svg-toc"></use></svg></span> 190 </label> 191 </div> 192 </header> 193 <aside class="sidebar-drawer"> 194 <div class="sidebar-container"> 195 196 <div class="sidebar-sticky"><a class="sidebar-brand" href="../index.html"> 197 <div class="sidebar-logo-container"> 198 <img class="sidebar-logo only-light" src="../_static/psycopg.png" alt="Light Logo"/> 199 <img class="sidebar-logo only-dark" src="../_static/psycopg.png" alt="Dark Logo"/> 200 </div> 201 202 <span class="sidebar-brand-text">psycopg 3.3.7.dev1 documentation</span> 203 204</a><form class="sidebar-search-container" method="get" action="../search.html" role="search"> 205 <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search"> 206 <input type="hidden" name="check_keywords" value="yes"> 207 <input type="hidden" name="area" value="default"> 208</form> 209<div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree"> 210 <ul class="current"> 211<li class="toctree-l1 current has-children"><a class="reference internal" href="index.html">Getting started with Psycopg 3</a><input aria-label="Toggle navigation of Getting started with Psycopg 3" checked="" class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" role="switch" type="checkbox"/><label for="toctree-checkbox-1"><span class="icon"><svg><use href="#svg-arrow-right"></use></svg></span></label><ul class="current"> 212<li class="toctree-l2 current current-page"><a class="current reference internal" href="#">Installation</a></li> 213<li class="toctree-l2"><a class="reference internal" href="usage.html">Basic module usage</a></li> 214<li class="toctree-l2"><a class="reference internal" href="params.html">Passing parameters to SQL queries</a></li> 215<li class="toctree-l2"><a class="reference internal" href="tstrings.html">Template string queries</a></li> 216<li class="toctree-l2"><a class="reference internal" href="adapt.html">Adapting basic Python types</a></li> 217<li class="toctree-l2"><a class="reference internal" href="pgtypes.html">Adapting other PostgreSQL types</a></li> 218<li class="toctree-l2"><a class="reference internal" href="transactions.html">Transactions management</a></li> 219<li class="toctree-l2"><a class="reference internal" href="copy.html">Using COPY TO and COPY FROM</a></li> 220<li class="toctree-l2"><a class="reference internal" href="from_pg2.html">Differences from <code class="xref py py-obj docutils literal notranslate"><span class="pre">psycopg2</span></code></a></li> 221</ul> 222</li> 223<li class="toctree-l1 has-children"><a class="reference internal" href="../advanced/index.html">More advanced topics</a><input aria-label="Toggle navigation of More advanced topics" class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" role="switch" type="checkbox"/><label for="toctree-checkbox-2"><span class="icon"><svg><use href="#svg-arrow-right"></use></svg></span></label><ul> 224<li class="toctree-l2"><a class="reference internal" href="../advanced/async.html">Concurrent operations</a></li> 225<li class="toctree-l2"><a class="reference internal" href="../advanced/typing.html">Static Typing</a></li> 226<li class="toctree-l2"><a class="reference internal" href="../advanced/rows.html">Row factories</a></li> 227<li class="toctree-l2"><a class="reference internal" href="../advanced/pool.html">Connection pools</a></li> 228<li class="toctree-l2"><a class="reference internal" href="../advanced/cursors.html">Cursor types</a></li> 229<li class="toctree-l2"><a class="reference internal" href="../advanced/adapt.html">Data adaptation configuration</a></li> 230<li class="toctree-l2"><a class="reference internal" href="../advanced/prepare.html">Prepared statements</a></li> 231<li class="toctree-l2"><a class="reference internal" href="../advanced/pipeline.html">Pipeline mode support</a></li> 232</ul> 233</li> 234<li class="toctree-l1 has-children"><a class="reference internal" href="../api/index.html">Psycopg 3 API</a><input aria-label="Toggle navigation of Psycopg 3 API" class="toctree-checkbox" id="toctree-checkbox-3" name="toctree-checkbox-3" role="switch" type="checkbox"/><label for="toctree-checkbox-3"><span class="icon"><svg><use href="#svg-arrow-right"></use></svg></span></label><ul> 235<li class="toctree-l2"><a class="reference internal" href="../api/module.html">The <code class="xref py py-obj docutils literal notranslate"><span class="pre">psycopg</span></code> module</a></li> 236<li class="toctree-l2"><a class="reference internal" href="../api/connections.html">Connection classes</a></li> 237<li class="toctree-l2"><a class="reference internal" href="../api/cursors.html">Cursor classes</a></li> 238<li class="toctree-l2"><a class="reference internal" href="../api/copy.html">COPY-related objects</a></li> 239<li class="toctree-l2"><a class="reference internal" href="../api/objects.html">Other top-level objects</a></li> 240<li class="toctree-l2"><a class="reference internal" href="../api/sql.html"><code class="xref py py-obj docutils literal notranslate"><span class="pre">sql</span></code> â SQL string composition</a></li> 241<li class="toctree-l2"><a class="reference internal" href="../api/rows.html"><code class="xref py py-obj docutils literal notranslate"><span class="pre">rows</span></code> â row factory implementations</a></li> 242<li class="toctree-l2"><a class="reference internal" href="../api/errors.html"><code class="xref py py-obj docutils literal notranslate"><span class="pre">errors</span></code> â Package exceptions</a></li> 243<li class="toctree-l2"><a class="reference internal" href="../api/pool.html"><code class="xref py py-obj docutils literal notranslate"><span class="pre">psycopg_pool</span></code> â Connection pool implementations</a></li> 244<li class="toctree-l2"><a class="reference internal" href="../api/conninfo.html"><code class="xref py py-obj docutils literal notranslate"><span class="pre">conninfo</span></code> â manipulate connection strings</a></li> 245<li class="toctree-l2"><a class="reference internal" href="../api/adapt.html"><code class="xref py py-obj docutils literal notranslate"><span class="pre">adapt</span></code> â Types adaptation</a></li> 246<li class="toctree-l2"><a class="reference internal" href="../api/types.html"><code class="xref py py-obj docutils literal notranslate"><span class="pre">types</span></code> â Types information and adapters</a></li> 247<li class="toctree-l2"><a class="reference internal" href="../api/abc.html"><code class="xref py py-obj docutils literal notranslate"><span class="pre">abc</span></code> â Psycopg abstract classes</a></li> 248<li class="toctree-l2"><a class="reference internal" href="../api/pq.html"><code class="xref py py-obj docutils literal notranslate"><span class="pre">pq</span></code> â libpq wrapper module</a></li> 249<li class="toctree-l2"><a class="reference internal" href="../api/crdb.html"><code class="xref py py-obj docutils literal notranslate"><span class="pre">crdb</span></code> â CockroachDB support</a></li> 250<li class="toctree-l2"><a class="reference internal" href="../api/dns.html"><code class="xref py py-obj docutils literal notranslate"><span class="pre">_dns</span></code> â DNS resolution utilities</a></li> 251</ul> 252</li> 253</ul> 254<ul> 255<li class="toctree-l1"><a class="reference internal" href="../news.html"><code class="docutils literal notranslate"><span class="pre">psycopg</span></code> release notes</a></li> 256<li class="toctree-l1"><a class="reference internal" href="../news_pool.html"><code class="docutils literal notranslate"><span class="pre">psycopg_pool</span></code> release notes</a></li> 257</ul> 258 259</div> 260</div> 261 262 </div> 263 264 </div> 265 </aside> 266 <div class="main"> 267 <div class="content"> 268 <div class="article-container"> 269 <a href="#" class="back-to-top muted-link"> 270 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"> 271 <path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path> 272 </svg>
273 <span>Back to top</span> 274 </a> 275 <div class="content-icon-container"> 276 277 278<div class="theme-toggle-container theme-toggle-content"> 279 <button class="theme-toggle" aria-label="Toggle Light / Dark / Auto color theme"> 280 <svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg> 281 <svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg> 282 <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg> 283 <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg> 284 </button> 285 </div> 286 <label class="toc-overlay-icon toc-content-icon" for="__toc"> 287 <span class="icon"><svg><use href="#svg-toc"></use></svg></span> 288 </label> 289 </div> 290 <article role="main" id="furo-main-content"> 291 <section id="installation"> 292<span id="id1"></span><h1>Installation<a class="headerlink" href="#installation" title="Link to this heading">¶</a></h1> 293<p>In short, if you use one of the <a class="reference internal" href="#supported-systems"><span class="std std-ref">supported systems</span></a>, 294run:</p> 295<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="o">--</span><span class="n">upgrade</span> <span class="n">pip</span> 296<span class="n">pip</span> <span class="n">install</span> <span class="s2">"psycopg[binary]"</span> 297</pre></div> 298</div> 299<p>and you should be <a class="reference internal" href="usage.html#module-usage"><span class="std std-ref">ready to start</span></a>. Read further for 300alternative ways to install.</p> 301<div class="admonition note"> 302<p class="admonition-title">Note</p> 303<p>Fun fact: there is no <code class="docutils literal notranslate"><span class="pre">psycopg3</span></code> package, only <code class="docutils literal notranslate"><span class="pre">psycopg</span></code>!</p> 304</div> 305<section id="supported-systems"> 306<span id="id2"></span><h2>Supported systems<a class="headerlink" href="#supported-systems" title="Link to this heading">¶</a></h2> 307<p>The Psycopg version documented here has <em>official and tested</em> support for:</p> 308<ul class="simple"> 309<li><p>Python: from version 3.10 to 3.15</p> 310<ul> 311<li><p>Python 3.8 and 3.9 are supported before Psycopg 3.3</p></li> 312<li><p>Python 3.7 is supported before Psycopg 3.2</p></li> 313<li><p>Python 3.6 is supported before Psycopg 3.1</p></li> 314</ul> 315</li> 316<li><p>PyPy: from version 3.10 to 3.11</p> 317<ul> 318<li><p>PyPy 3.9 is supported before Psycopg 3.3</p></li> 319<li><p><strong>Note:</strong> Only the pure Python installation is currently supported.</p></li> 320</ul> 321</li> 322<li><p>PostgreSQL: from version 10 to 18</p> 323<ul> 324<li><p><strong>Note:</strong> PostgreSQL <a class="reference external" href="https://www.postgresql.org/support/versioning/">currently supported release</a> are actively tested 325in the CI. Out-of-support releases are supported on a best-effort basis.</p></li> 326</ul> 327</li> 328<li><p>OS: Linux, macOS, Windows</p></li> 329<li><p>Pip: 20.3 or newer</p></li> 330</ul> 331<p>The tests to verify the supported systems run in <a class="reference external" href="https://github.com/psycopg/psycopg/actions">Github workflows</a>: 332anything that is not tested there is not officially supported. This includes:</p> 333<ul class="simple"> 334<li><p>Unofficial Python distributions such as Conda;</p></li> 335<li><p>Alternative PostgreSQL implementation;</p></li> 336<li><p>Other platforms such as BSD or Solaris.</p></li> 337</ul> 338<p>If you use an unsupported system, things might work (because, for instance, the 339database may use the same wire protocol as PostgreSQL) but we cannot guarantee 340the correct working or a smooth ride.</p> 341</section> 342<section id="what-to-install"> 343<span id="install-grid"></span><h2>What to install?<a class="headerlink" href="#what-to-install" title="Link to this heading">¶</a></h2> 344<p>There are a few different options to install Psycopg 3. This is a quick 345summary of their differences; follow the links for more details.</p> 346<div class="table-wrapper docutils container"> 347<table class="docutils align-default"> 348<thead> 349<tr class="row-odd"><th class="head"><p>Installation Option</p></th> 350<th class="head"><p>Command</p></th> 351<th class="head"><p>Description</p></th> 352<th class="head"><p>PerforÂmance</p></th> 353<th class="head"><p>Needs Local libpq?</p></th> 354<th class="head"><p>Needs Build Tools?</p></th> 355</tr> 356</thead> 357<tbody> 358<tr class="row-even"><td><p><a class="reference internal" href="#binary-installation"><span class="std std-ref">Binary installation</span></a> (recommended for most users)</p></td> 359<td><p><code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">psycopg[binary]</span></code></p></td> 360<td><p>Precompiled C extensions, packaged with client libraries.</p></td> 361<td><p>ð Fast</p></td> 362<td><p>â No</p></td> 363<td><p>â No</p></td> 364</tr> 365<tr class="row-odd"><td><p><a class="reference internal" href="#local-installation"><span class="std std-ref">Local installation</span></a></p></td> 366<td><p><code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">psycopg[c]</span></code></p></td> 367<td><p>Builds C extensions from source. 368Requires build tools and client libraries.</p></td> 369<td><p>ð Fast</p></td> 370<td><p>â Yes</p></td> 371<td><p>â Yes</p></td> 372</tr> 373<tr class="row-even"><td><p><a class="reference internal" href="#pure-python-installation"><span class="std std-ref">Pure Python installation</span></a></p></td> 374<td><p><code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">psycopg</span></code></p></td> 375<td><p>Pure Python implementation only. Requires client libraries.</p></td> 376<td><p>ð¢ Slow</p></td> 377<td><p>â Yes</p></td> 378<td><p>â No</p></td> 379</tr> 380</tbody> 381</table> 382</div> 383</section> 384<section id="binary-installation"> 385<span id="id5"></span><h2>Binary installation<a class="headerlink" href="#binary-installation" title="Link to this heading">¶</a></h2> 386<p>The quickest way to start developing with Psycopg 3 is to install the binary 387packages by running:</p> 388<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="s2">"psycopg[binary]"</span> 389</pre></div> 390</div> 391<p>This will install a self-contained package with all the libraries needed. 392If you are coming from Psycopg 2, this is the equivalent of installing 393the <code class="docutils literal notranslate"><span class="pre">psycopg2-binary</span></code> package.</p> 394<div class="admonition seealso"> 395<p class="admonition-title">See also</p> 396<p>Did Psycopg 3 install ok? Great! You can now move on to the <a class="reference internal" href="usage.html#module-usage"><span class="std std-ref">basic 397module usage</span></a> to learn how it works.</p> 398<p>Keep on reading if the above method didnât work and you need a different 399way to install Psycopg 3.</p> 400<p>For further information about the differences between the packages see 401<a class="reference internal" href="../api/pq.html#pq-impl"><span class="std std-ref">pq module implementations</span></a>.</p> 402</div> 403<p>If your platform is not supported, or if the libpq packaged is not suitable, 404you should proceed to a <a class="reference internal" href="#local-installation"><span class="std std-ref">local installation</span></a> or a 405<a class="reference internal" href="#pure-python-installation"><span class="std std-ref">pure Python installation</span></a>.</p> 406<div class="admonition note"> 407<p class="admonition-title">Note</p> 408<p>Binary packages are produced on a best-effort basis; the supported 409platforms depend on the CI runners available to build the 410packages. This means that:</p> 411<ul class="simple"> 412<li><p>binary packages for a new version of Python are made available once
413the runners used for the build support it. You can check the 414<a class="reference external" href="https://pypi.org/project/psycopg-binary/#files">psycopg-binary PyPI files</a> to verify whether your platform is 415supported;</p></li> 416<li><p>the libpq version included in the binary packages depends on the version 417available on the runners. You can use the <a class="reference internal" href="../api/pq.html#psycopg.pq.version" title="psycopg.pq.version"><code class="xref py py-obj docutils literal notranslate"><span class="pre">psycopg.pq.version()</span></code></a> 418function and <a class="reference internal" href="../api/pq.html#psycopg.pq.__build_version__" title="psycopg.pq.__build_version__"><code class="xref py py-obj docutils literal notranslate"><span class="pre">__build_version__</span></code></a> constant to infer the 419features available.</p></li> 420</ul> 421</div> 422<div class="admonition warning"> 423<p class="admonition-title">Warning</p> 424<ul class="simple"> 425<li><p>Starting from Psycopg 3.1.20, ARM64 macOS binary packages (i.e. for 426Apple M1 machines) are no more available for macOS versions before 14.0. 427Please upgrade your OS to at least 14.0 or use a <a class="reference internal" href="#local-installation"><span class="std std-ref">local</span></a> or a <a class="reference internal" href="#pure-python-installation"><span class="std std-ref">Python</span></a> 428installation.</p></li> 429<li><p>The binary installation is not supported by PyPy.</p></li> 430</ul> 431</div> 432</section> 433<section id="local-installation"> 434<span id="id7"></span><h2>Local installation<a class="headerlink" href="#local-installation" title="Link to this heading">¶</a></h2> 435<p>A âLocal installationâ results in a performing and maintainable library. The 436library will include the speed-up C module and will be linked to the system 437libraries (<code class="docutils literal notranslate"><span class="pre">libpq</span></code>, <code class="docutils literal notranslate"><span class="pre">libssl</span></code>â¦) so that system upgrade of libraries will 438upgrade the libraries used by Psycopg 3 too. This is the preferred way to 439install Psycopg for a production site.</p> 440<p>In order to perform a local installation you need some prerequisites:</p> 441<ul class="simple"> 442<li><p>a C compiler,</p></li> 443<li><p>Python development headers (e.g. the <code class="docutils literal notranslate"><span class="pre">python3-dev</span></code> package).</p></li> 444<li><p>PostgreSQL client development headers (e.g. the <code class="docutils literal notranslate"><span class="pre">libpq-dev</span></code> package).</p></li> 445<li><p>The <strong class="program">pg_config</strong> program available in the <span class="target" id="index-0"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code>.</p></li> 446</ul> 447<p>You <strong>must be able</strong> to troubleshoot an extension build, for instance you must 448be able to read your compilerâs error message. If you are not, please donât 449try this and use the <a class="reference internal" href="#binary-installation"><span class="std std-ref">Binary installation</span></a> instead.</p> 450<p>If your build prerequisites are in place you can run:</p> 451<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="s2">"psycopg[c]"</span> 452</pre></div> 453</div> 454<p>This will install a self-contained package with all the libraries needed. 455If you are coming from Psycopg 2, this is the equivalent of installing 456the <code class="docutils literal notranslate"><span class="pre">psycopg2</span></code> package, both in terms of build requirements and system 457dependencies at runtime.</p> 458<div class="admonition warning"> 459<p class="admonition-title">Warning</p> 460<p>The local installation is not supported by PyPy.</p> 461</div> 462</section> 463<section id="pure-python-installation"> 464<span id="id8"></span><h2>Pure Python installation<a class="headerlink" href="#pure-python-installation" title="Link to this heading">¶</a></h2> 465<p>If you simply install:</p> 466<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">psycopg</span> 467</pre></div> 468</div> 469<p>without <code class="docutils literal notranslate"><span class="pre">[c]</span></code> or <code class="docutils literal notranslate"><span class="pre">[binary]</span></code> extras you will obtain a pure Python 470implementation. This is particularly handy for debugging and hacking.</p> 471<div class="admonition warning"> 472<p class="admonition-title">Warning</p> 473<p>The pure Python installation is much slower than the 474<a class="reference internal" href="#binary-installation"><span class="std std-ref">Binary installation</span></a> or <a class="reference internal" href="#local-installation"><span class="std std-ref">Local installation</span></a>. It is likely 475sufficient for local developments or small tasks but, for production loads, 476you might want to install one of the speed-up extensions too.</p> 477</div> 478<p>In order to use the pure Python installation you will need the <code class="docutils literal notranslate"><span class="pre">libpq</span></code> 479PostgreSQL client library installed on your client (which will be imported 480dynamically via <a class="reference external" href="https://docs.python.org/3/library/ctypes.html#module-ctypes" title="(in Python v3.14)"><code class="xref py py-obj docutils literal notranslate"><span class="pre">ctypes</span></code></a>); for example on Debian systems you will probably 481need:</p> 482<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sudo</span> <span class="n">apt</span> <span class="n">install</span> <span class="n">libpq5</span> 483</pre></div> 484</div> 485<p>If you are not able to fulfill this requirement please use a 486<a class="reference internal" href="#binary-installation"><span class="std std-ref">Binary installation</span></a>, which packages its own copy of the <code class="docutils literal notranslate"><span class="pre">libpq</span></code>.</p> 487<div class="admonition note"> 488<p class="admonition-title">Note</p> 489<p>The <code class="docutils literal notranslate"><span class="pre">libpq</span></code> is the client library also used by <strong class="program">
489psql</strong>, the 490PostgreSQL command line client, to connect to the database. On most 491systems, installing <strong class="program">psql</strong> will install the <code class="docutils literal notranslate"><span class="pre">libpq</span></code> too as a 492dependency.</p> 493</div> 494</section> 495<section id="installing-the-connection-pool"> 496<span id="pool-installation"></span><h2>Installing the connection pool<a class="headerlink" href="#installing-the-connection-pool" title="Link to this heading">¶</a></h2> 497<p>The <a class="reference internal" href="../advanced/pool.html#connection-pools"><span class="std std-ref">Psycopg connection pools</span></a> are distributed in a 498separate package from the <code class="xref py py-obj docutils literal notranslate"><span class="pre">psycopg</span></code> package itself, in order to allow a 499different release cycle.</p> 500<p>In order to use the pool you must install the <code class="docutils literal notranslate"><span class="pre">pool</span></code> extra, using <code class="docutils literal notranslate"><span class="pre">pip</span> 501<span class="pre">install</span> <span class="pre">"psycopg[pool]"</span></code>, or install the <a class="reference internal" href="../api/pool.html#module-psycopg_pool" title="psycopg_pool"><code class="xref py py-obj docutils literal notranslate"><span class="pre">psycopg_pool</span></code></a> package separately, 502which would allow to specify the release to install more precisely.</p> 503</section> 504<section id="handling-dependencies"> 505<span id="install-dependencies"></span><h2>Handling dependencies<a class="headerlink" href="#handling-dependencies" title="Link to this heading">¶</a></h2> 506<p>If you need to specify your project dependencies (for instance in a 507<code class="docutils literal notranslate"><span class="pre">requirements.txt</span></code> file, <code class="docutils literal notranslate"><span class="pre">setup.py</span></code>, <code class="docutils literal notranslate"><span class="pre">pyproject.toml</span></code> dependenciesâ¦) 508you should probably specify one of the following:</p> 509<ul class="simple"> 510<li><p>If your project is a library, add a dependency on <code class="docutils literal notranslate"><span class="pre">psycopg</span></code>. This will 511make sure that your library will have the <code class="docutils literal notranslate"><span class="pre">psycopg</span></code> package with the right 512interface and leaves the possibility of choosing a specific implementation 513to the end user of your library.</p></li> 514<li><p>If your project is a final application (e.g. a service running on a server) 515you can require a specific implementation, for instance <code class="docutils literal notranslate"><span class="pre">psycopg[c]</span></code>, 516after you have made sure that the prerequisites are met (e.g. the depending 517libraries and tools are installed in the host machine).</p></li> 518</ul> 519<p>In both cases you can specify which version of Psycopg to use using 520<a class="reference external" href="https://pip.pypa.io/en/stable/reference/requirement-specifiers/">requirement specifiers</a>.</p> 521<p>If you want to make sure that a specific implementation is used you can 522specify the <span class="target" id="index-1"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PSYCOPG_IMPL</span></code> environment variable: importing the library 523will fail if the implementation specified is not available. See <a class="reference internal" href="../api/pq.html#pq-impl"><span class="std std-ref">pq module implementations</span></a>.</p> 524</section> 525</section> 526 527 </article> 528 </div> 529 <footer> 530 531 <div class="related-pages"> 532 <a class="next-page" href="usage.html"> 533 <div class="page-info"> 534 <div class="context"> 535 <span>Next</span> 536 </div> 537 <div class="title">Basic module usage</div> 538 </div> 539 <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> 540 </a> 541 <a class="prev-page" href="index.html"> 542 <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> 543 <div class="page-info"> 544 <div class="context">
545 <span>Previous</span> 546 </div> 547 548 <div class="title">Getting started with Psycopg 3</div> 549 550 </div> 551 </a> 552 </div> 553 <div class="bottom-of-page"> 554 <div class="left-details"> 555 <div class="copyright"> 556 Copyright © 2020, Daniele Varrazzo and The Psycopg Team 557 </div> 558 Made with <a href="https://www.sphinx-doc.org/">Sphinx</a> and 559 <a href="https://github.com/pradyunsg/furo">Furo</a> 560 561 </div> 562 <div class="right-details"> 563 564 </div> 565 </div> 566 567 </footer> 568 </div> 569 <aside class="toc-drawer"> 570 571 572 <div class="toc-sticky toc-scroll"> 573 <div class="toc-title-container"> 574 <span class="toc-title"> 575 On this page 576 </span> 577 </div> 578 <div class="toc-tree-container"> 579 <div class="toc-tree"> 580 <ul> 581<li><a class="reference internal" href="#">Installation</a><ul> 582<li><a class="reference internal" href="#supported-systems">Supported systems</a></li> 583<li><a class="reference internal" href="#what-to-install">What to install?</a></li> 584<li><a class="reference internal" href="#binary-installation">Binary installation</a></li> 585<li><a class="reference internal" href="#local-installation">Local installation</a></li> 586<li><a class="reference internal" href="#pure-python-installation">Pure Python installation</a></li> 587<li><a class="reference internal" href="#installing-the-connection-pool">Installing the connection pool</a></li> 588<li><a class="reference internal" href="#handling-dependencies">Handling dependencies</a></li> 589</ul> 590</li> 591</ul> 592 593 </div> 594 </div> 595 </div> 596 597 598 </aside> 599 </div> 600</div>
600<script src="../_static/documentation_options.js?v=e4c94ff0"></script>
600 601
601<script src="../_static/doctools.js?v=fd6eb6e6"></script>
601 602
602<script src="../_static/sphinx_highlight.js?v=6ffebe34"></script>
602 603
603<script src="../_static/scripts/furo.js?v=46bd48cc"></script>
603 604
604<script type="module" src="https://static.cloudflareinsights.com/beacon.min.js/v31edd6df95cf4e85bb4c19e7a9bdbcba1788362987495" integrity="sha512-iIg7k2xntmwu6/uSb5tpc/hySgZc4eoL31yB29W6tJFo2akwjPWcEqnCEdJvGexCL0KEQwVYv5BlowfhVz26hg==" data-cf-beacon='{"version":"2024.11.0","token":"fd1fd7e322bb48aaab6414c3a1ead9d8","r":1,"spa":2}' crossorigin="anonymous"></script>
604 605</body> 606</html>
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.