matplotlib.github.com/3.3.2/users/installing.html at main · matplotlib/matplotlib.github.com

History

409 lines (388 loc) · 26.6 KB

Raw

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

349

350

351

352

353

354

355

356

357

358

359

360

361

362

363

364

365

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

381

382

383

384

385

386

387

388

389

390

391

392

393

394

395

396

397

398

399

400

401

402

403

404

405

406

407

408

409

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<head>

<title>Installation Guide — Matplotlib 3.3.2 documentation</title>

title="Search within Matplotlib 3.3.2 documentation"

href="../_static/opensearch.xml"/>

</head><body>

<div id="unreleased-message"> You are reading an old version of the documentation (v3.3.2). For the latest version see <a href="https://matplotlib.org/stable/users/installing.html">https://matplotlib.org/stable/users/installing.html</a></div>

<!--

</div>

-->

<div style="float: left; position: absolute; width: 496px; bottom: 0; padding-bottom: 24px"><span style="float: right; color: #789; background: white">Version 3.3.2</span></div>

<div id="forkongithub"><a href="https://github.com/matplotlib/matplotlib">Fork me on GitHub</a></div>

</div>

<ul>

<li><a href="#">Installation</a></li>

<li><a href="../contents.html">Documentation</a></li>

<li><a href="../gallery/index.html">Examples</a></li>

<li><a href="../tutorials/index.html">Tutorials</a></li>

<li><a href="../devel/index.html">Contributing</a></li>

</form>

</li>

</ul>

</nav>

<h3>Navigation</h3>

<ul>

<a href="../genindex.html" title="General Index"

accesskey="I">index</a></li>

<a href="../py-modindex.html" title="Python Module Index"

>modules</a> |</li>

<a href="../tutorials/index.html" title="Tutorials"

accesskey="N">next</a> |</li>

<a href="index.html" title="User's Guide"

accesskey="P">previous</a> |</li>

<li><a href="../contents.html">contents</a> »</li>

<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">User's Guide</a> »</li>

<li class="nav-item nav-item-this"><a href="">Installation Guide</a></li>

</ul>

</div>

<h3><a href="../contents.html">Table of Contents</a></h3>

<ul>

<li><a class="reference internal" href="#">Installation Guide</a><ul>

<li><a class="reference internal" href="#installing-an-official-release">Installing an official release</a><ul>

</ul>

</li>

<li><a class="reference internal" href="#third-party-distributions-of-matplotlib">Third-party distributions of Matplotlib</a><ul>

<li><a class="reference internal" href="#scientific-python-distributions">Scientific Python Distributions</a></li>

<li><a class="reference internal" href="#linux-using-your-package-manager">Linux: using your package manager</a></li>

</ul>

</li>

<li><a class="reference internal" href="#installing-from-source">Installing from source</a><ul>

<li><a class="reference internal" href="#dependencies">Dependencies</a></li>

<li><a class="reference internal" href="#freetype-and-qhull">FreeType and Qhull</a></li>

<li><a class="reference internal" href="#building-on-windows">Building on Windows</a></li>

<li><a class="reference internal" href="#conda-packages">Conda packages</a></li>

</ul>

</li>

</ul>

</li>

</ul>

<h3>Related Topics</h3>

<ul>

<li><a href="../contents.html">Documentation overview</a><ul>

<li><a href="index.html">User's Guide</a><ul>

<li>Previous: <a href="index.html" title="previous chapter">User's Guide</a></li>

<li>Next: <a href="../tutorials/index.html" title="next chapter">Tutorials</a></li>

</ul></li>

</ul>

</div>

<div id="sidebar-pagesource" role="note" aria-label="source link"

style="margin-top: 1.5em; padding-top: 0.1em; border-top: 1px solid #86989b">

<a href="../_sources/users/installing.rst.txt"

style="color: #c0c0c0" rel="nofollow">Show Page Source</a>

</div>

<h1><a class="toc-backref" href="#id7">Installation Guide</a><a class="headerlink" href="#installation-guide" title="Permalink to this headline">¶</a></h1>

<p class="last">If you wish to contribute to the project, it's recommended you

<a class="reference internal" href="#install-from-source"><span class="std std-ref">install the latest development version</span></a>.</p>

</div>

<p class="topic-title">Contents</p>

<li><a class="reference internal" href="#installation-guide" id="id7">Installation Guide</a><ul>

<li><a class="reference internal" href="#installing-an-official-release" id="id8">Installing an official release</a><ul>

</ul>

</li>

<li><a class="reference internal" href="#third-party-distributions-of-matplotlib" id="id10">Third-party distributions of Matplotlib</a><ul>

<li><a class="reference internal" href="#scientific-python-distributions" id="id11">Scientific Python Distributions</a></li>

<li><a class="reference internal" href="#linux-using-your-package-manager" id="id12">Linux: using your package manager</a></li>

</ul>

</li>

<li><a class="reference internal" href="#installing-from-source" id="id13">Installing from source</a><ul>

<li><a class="reference internal" href="#dependencies" id="id14">Dependencies</a></li>

<li><a class="reference internal" href="#freetype-and-qhull" id="id15">FreeType and Qhull</a></li>

<li><a class="reference internal" href="#building-on-windows" id="id16">Building on Windows</a></li>

<li><a class="reference internal" href="#conda-packages" id="id17">Conda packages</a></li>

</ul>

</li>

</ul>

</li>

</ul>

</div>

<h2><a class="toc-backref" href="#id8">Installing an official release</a><a class="headerlink" href="#installing-an-official-release" title="Permalink to this headline">¶</a></h2>

<p>Matplotlib and its dependencies are available as wheel packages for macOS,

Windows and Linux distributions:</p>

<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">pip</span> <span class="n">install</span> <span class="o">-</span><span class="n">U</span> <span class="n">pip</span>

<span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">pip</span> <span class="n">install</span> <span class="o">-</span><span class="n">U</span> <span class="n">matplotlib</span>

</pre></div>

</div>

<p>If this command results in Matplotlib being compiled from source and

there's trouble with the compilation, you can add <code class="docutils literal notranslate"><span class="pre">--prefer-binary</span></code> to

select the newest version of Matplotlib for which there is a

precompiled wheel for your OS and Python.</p>

<p>The following backends work out of the box: Agg, ps, pdf, svg</p>

<p>Python is typically shipped with tk bindings which are used by

TkAgg.</p>

<p class="last">For support of other GUI frameworks, LaTeX rendering, saving

animations and a larger selection of file formats, you need to

install <a class="reference internal" href="#install-requirements"><span class="std std-ref">additional dependencies</span></a>.</p>

</div>

<p>Although not required, we suggest also installing <code class="docutils literal notranslate"><span class="pre">IPython</span></code> for

interactive use. To easily install a complete Scientific Python

stack, see <a class="reference internal" href="#install-scipy-dists"><span class="std std-ref">Scientific Python Distributions</span></a> below.</p>

<p>The wheels (<code class="file docutils literal notranslate"><span class="pre">*.whl</span></code>) on the <a class="reference external" href="https://pypi.org/project/matplotlib/">PyPI download page</a> do not contain test data

or example code.</p>

<p>If you want to try the many demos that come in the Matplotlib source

distribution, download the <code class="file docutils literal notranslate"><span class="pre">*.tar.gz</span></code> file and look in the

<code class="file docutils literal notranslate"><span class="pre">examples</span></code> subdirectory.</p>

<p>To run the test suite:</p>

<li>extract the <code class="file docutils literal notranslate"><span class="pre">lib/matplotlib/tests</span></code> or <code class="file docutils literal notranslate"><span class="pre">lib/mpl_toolkits/tests</span></code>

directories from the source distribution.</li>

<li>install test dependencies: <a class="reference external" href="https://pypi.org/project/pytest">pytest</a>,

MiKTeX, GhostScript, ffmpeg, avconv, ImageMagick, and <a class="reference external" href="https://inkscape.org/">Inkscape</a>.</li>

<li>run <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-mpytest</span></code>.</li>

</ul>

</div>

<h2><a class="toc-backref" href="#id10">Third-party distributions of Matplotlib</a><a class="headerlink" href="#third-party-distributions-of-matplotlib" title="Permalink to this headline">¶</a></h2>

<span id="install-scipy-dists"></span><h3><a class="toc-backref" href="#id11">Scientific Python Distributions</a><a class="headerlink" href="#scientific-python-distributions" title="Permalink to this headline">¶</a></h3>

<p><a class="reference external" href="https://www.anaconda.com/">Anaconda</a> and <a class="reference external" href="https://www.activestate.com/activepython/downloads">ActiveState</a> are excellent

choices that "just work" out of the box for Windows, macOS and common

Linux platforms. <a class="reference external" href="https://winpython.github.io/">WinPython</a> is an

option for Windows users. All of these distributions include

Matplotlib and <em>lots</em> of other useful (data) science tools.</p>

</div>

<h3><a class="toc-backref" href="#id12">Linux: using your package manager</a><a class="headerlink" href="#linux-using-your-package-manager" title="Permalink to this headline">¶</a></h3>

<p>If you are on Linux, you might prefer to use your package manager. Matplotlib

is packaged for almost every major Linux distribution.</p>

<li>Debian / Ubuntu: <code class="docutils literal notranslate"><span class="pre">sudo</span> <span class="pre">apt-get</span> <span class="pre">install</span> <span class="pre">python3-matplotlib</span></code></li>

<li>Fedora: <code class="docutils literal notranslate"><span class="pre">sudo</span> <span class="pre">dnf</span> <span class="pre">install</span> <span class="pre">python3-matplotlib</span></code></li>

<li>Red Hat: <code class="docutils literal notranslate"><span class="pre">sudo</span> <span class="pre">yum</span> <span class="pre">install</span> <span class="pre">python3-matplotlib</span></code></li>

<li>Arch: <code class="docutils literal notranslate"><span class="pre">sudo</span> <span class="pre">pacman</span> <span class="pre">-S</span> <span class="pre">python-matplotlib</span></code></li>

</ul>

</div>

<span id="install-from-source"></span><h2><a class="toc-backref" href="#id13">Installing from source</a><a class="headerlink" href="#installing-from-source" title="Permalink to this headline">¶</a></h2>

<p>If you are interested in contributing to Matplotlib development,

running the latest source code, or just like to build everything

yourself, it is not difficult to build Matplotlib from source. Grab

the latest <em>tar.gz</em> release file from <a class="reference external" href="https://pypi.org/project/matplotlib/">the PyPI files page</a>, or if you want to

develop Matplotlib or just need the latest bugfixed version, grab the

latest git version, and see <a class="reference internal" href="../faq/installing_faq.html#install-from-git"><span class="std std-ref">Install from source</span></a>.</p>

<p>Matplotlib can be installed from the source directory with a simple</p>

</pre></div>

</div>

<p>We provide a <a class="reference external" href="https://raw.githubusercontent.com/matplotlib/matplotlib/master/setup.cfg.template">setup.cfg</a> file which you can use to customize the build

process. For example, which default backend to use, whether some of the

optional libraries that Matplotlib ships with are installed, and so on. This

file will be particularly useful to those packaging Matplotlib.</p>

<span id="install-requirements"></span><h3><a class="toc-backref" href="#id14">Dependencies</a><a class="headerlink" href="#dependencies" title="Permalink to this headline">¶</a></h3>

<p>Matplotlib requires the following dependencies:</p>

<li><a class="reference external" href="https://www.python.org/downloads/">Python</a> (>= 3.6)</li>

<li><a class="reference external" href="https://numpy.org">NumPy</a> (>= 1.15)</li>

<li><a class="reference external" href="https://setuptools.readthedocs.io/en/latest/">setuptools</a></li>

<li><a class="reference external" href="https://matplotlib.org/cycler/">cycler</a> (>= 0.10.0)</li>

<li><a class="reference external" href="https://pypi.org/project/python-dateutil">dateutil</a> (>= 2.1)</li>

<li><a class="reference external" href="https://github.com/nucleic/kiwi">kiwisolver</a> (>= 1.0.0)</li>

<li><a class="reference external" href="https://pillow.readthedocs.io/en/latest/">Pillow</a> (>= 6.2)</li>

<li><a class="reference external" href="https://pypi.org/project/pyparsing/">pyparsing</a> (>=2.0.3)</li>

</ul>

<p>Optionally, you can also install a number of packages to enable better user

interface toolkits. See <a class="reference internal" href="../tutorials/introductory/usage.html#what-is-a-backend"><span class="std std-ref">What is a backend?</span></a> for more details on the

optional Matplotlib backends and the capabilities they provide.</p>

<li><a class="reference external" href="https://docs.python.org/3/library/tk.html">Tk</a> (>= 8.3, != 8.6.0 or 8.6.1): for the Tk-based backends.</li>

<li><a class="reference external" href="https://pypi.org/project/PyQt4">PyQt4</a> (>= 4.6) or <a class="reference external" href="https://pypi.org/project/PySide">PySide</a> (>= 1.0.3) <a class="footnote-reference" href="#id4" id="id1">[1]</a>: for the Qt4-based backends.</li>

<li><a class="reference external" href="https://pypi.org/project/PyQt5">PyQt5</a> or <a class="reference external" href="https://pypi.org/project/PySide2">PySide2</a>: for the Qt5-based backends.</li>

<li><a class="reference external" href="https://pygobject.readthedocs.io/en/latest/">PyGObject</a>: for the GTK3-based backends <a class="footnote-reference" href="#id5" id="id2">[2]</a>.</li>

<li><a class="reference external" href="https://www.wxpython.org/">wxPython</a> (>= 4) <a class="footnote-reference" href="#id6" id="id3">[3]</a>: for the wx-based backends.</li>

<li><a class="reference external" href="https://pycairo.readthedocs.io/en/latest/">pycairo</a> (>= 1.11.0) or <a class="reference external" href="https://cairocffi.readthedocs.io/en/latest/">cairocffi</a> (>= 0.8): for the GTK3 and/or cairo-based

backends.</li>

<li><a class="reference external" href="https://pypi.org/project/tornado">Tornado</a>: for the WebAgg backend.</li>

</ul>

<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>PySide cannot be pip-installed on Linux (but can be conda-installed).</td></tr>

</tbody>

</table>

<tr><td class="label"><a class="fn-backref" href="#id2">[2]</a></td><td>If using pip (and not conda), PyGObject must be built from source; see

<a class="reference external" href="https://pygobject.readthedocs.io/en/latest/devguide/dev_environ.html">https://pygobject.readthedocs.io/en/latest/devguide/dev_environ.html</a>.</td></tr>

</tbody>

</table>

<tr><td class="label"><a class="fn-backref" href="#id3">[3]</a></td><td>If using pip (and not conda) on Linux, wxPython wheels must be manually

downloaded from <a class="reference external" href="https://wxpython.org/pages/downloads/">https://wxpython.org/pages/downloads/</a>.</td></tr>

</tbody>

</table>

<p>For better support of animation output format and image file formats, LaTeX,

etc., you can install the following:</p>

<li><a class="reference external" href="https://www.ffmpeg.org/">ffmpeg</a>: for saving movies.</li>

<li><a class="reference external" href="https://www.imagemagick.org/script/index.php">ImageMagick</a>: for saving

animated gifs.</li>

<li><a class="reference external" href="https://www.latex-project.org/">LaTeX</a> (with <a class="reference external" href="https://ctan.org/pkg/cm-super">cm-super</a> ) and <a class="reference external" href="https://ghostscript.com/download/">GhostScript (>=9.0)</a> : for rendering text with

LaTeX.</li>

<li><a class="reference external" href="https://www.fontconfig.org">fontconfig</a> (>= 2.7): for detection of system

fonts on Linux.</li>

</ul>

</div>

<h3><a class="toc-backref" href="#id15">FreeType and Qhull</a><a class="headerlink" href="#freetype-and-qhull" title="Permalink to this headline">¶</a></h3>

<p>Matplotlib depends on <a class="reference external" href="https://www.freetype.org/">FreeType</a> (>=

2.3), a font rendering library, and on <a class="reference external" href="http://www.qhull.org/">Qhull</a> (>= 2015.2), a library for computing

triangulations. By default (except on AIX) Matplotlib downloads and

builds its own copy of FreeType (this is necessary to run the test

suite, because different versions of FreeType rasterize characters

differently), and uses its own copy of Qhull.</p>

<p>To force Matplotlib to use a copy of FreeType or Qhull already installed in

your system, create a <code class="file docutils literal notranslate"><span class="pre">setup.cfg</span></code> file with the following contents:</p>

<span class="na">system_freetype</span> <span class="o">=</span> <span class="s">true</span>

<span class="na">system_qhull</span> <span class="o">=</span> <span class="s">true</span>

</pre></div>

</div>

<p>before running <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-m</span> <span class="pre">pip</span> <span class="pre">install</span> <span class="pre">.</span></code>.</p>

<p>In this case, you need to install the FreeType and Qhull library and headers.

This can be achieved using a package manager, e.g. for FreeType:</p>

<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="c1"># Pick ONE of the following:</span>

sudo apt install libfreetype6-dev <span class="c1"># Debian/Ubuntu</span>

sudo dnf install freetype-devel <span class="c1"># Fedora</span>

brew install freetype <span class="c1"># macOS with Homebrew</span>

conda install freetype <span class="c1"># conda, any OS</span>

</pre></div>

</div>

<p>(adapt accordingly for Qhull).</p>

<p>On Linux and macOS, it is also recommended to install <a class="reference external" href="https://www.freedesktop.org/wiki/Software/pkg-config/">pkg-config</a>, a helper

tool for locating FreeType:</p>

<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="c1"># Pick ONE of the following:</span>

sudo apt install pkg-config <span class="c1"># Debian/Ubuntu</span>

sudo dnf install pkgconf <span class="c1"># Fedora</span>

brew install pkg-config <span class="c1"># macOS with Homebrew</span>

conda install pkg-config <span class="c1"># conda</span>

<span class="c1"># Or point the PKG_CONFIG environment variable to the path to pkg-config:</span>

<span class="nb">export</span> <span class="nv">PKG_CONFIG</span><span class="o">=</span>...

</pre></div>

</div>

<p>If not using pkg-config (in particular on Windows), you may need to set the

include path (to the library headers) and link path (to the libraries)

explicitly, if they are not in standard locations. This can be done using

standard environment variables -- on Linux and OSX:</p>

<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="nb">export</span> <span class="nv">CFLAGS</span><span class="o">=</span><span class="s1">'-I/directory/containing/ft2build.h'</span>

<span class="nb">export</span> <span class="nv">LDFLAGS</span><span class="o">=</span><span class="s1">'-L/directory/containing/libfreetype.so'</span>

</pre></div>

</div>

<p>and on Windows:</p>

<div class="highlight-bat notranslate"><div class="highlight"><pre><span></span><span class="k">set</span> <span class="nv">CL</span><span class="p">=</span>/IC:\directory\containing\ft2build.h

<span class="k">set</span> <span class="nv">LINK</span><span class="p">=</span>/LIBPATH:C:\directory\containing\freetype.lib

</pre></div>

</div>

<p>Matplotlib always uses its own copies of the following libraries:</p>

<li><code class="docutils literal notranslate"><span class="pre">Agg</span></code>: the Anti-Grain Geometry C++ rendering engine;</li>

<li><code class="docutils literal notranslate"><span class="pre">ttconv</span></code>: a TrueType font utility.</li>

</ul>

</div>

<h3><a class="toc-backref" href="#id16">Building on Windows</a><a class="headerlink" href="#building-on-windows" title="Permalink to this headline">¶</a></h3>

<p>Compiling Matplotlib (or any other extension module, for that matter) requires

Visual Studio 2015 or later.</p>

<p>If you are building your own Matplotlib wheels (or sdists), note that any DLLs

that you copy into the source tree will be packaged too.</p>

</div>

<h3><a class="toc-backref" href="#id17">Conda packages</a><a class="headerlink" href="#conda-packages" title="Permalink to this headline">¶</a></h3>

<p>The conda packaging scripts for Matplotlib are available at

<a class="reference external" href="https://github.com/conda-forge/matplotlib-feedstock">https://github.com/conda-forge/matplotlib-feedstock</a>.</p>

</div>

</div>

<br />

Last updated on Sep 15, 2020.

Created using

<a href="http://sphinx-doc.org/">Sphinx</a> 3.1.1.

Doc version 3.3.2.

</div>

</footer>

</body>

</html>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

installing.html

Latest commit

History

installing.html

File metadata and controls