Getting Started

Installation

schemdraw can be installed from pip using

pip install schemdraw

or to include optional matplotlib backend dependencies:

pip install schemdraw[matplotlib]

To allow the SVG drawing Backends to render math expressions, install the optional ziamath dependency with:

pip install schemdraw[svgmath]

Alternatively, schemdraw can be installed directly by downloading the source and running

pip install ./

Schemdraw requires Python 3.8 or higher.

Overview

The schemdraw module allows for drawing circuit elements. schemdraw.elements contains Basic Elements pre-defined for use in a drawing. A common import structure is:

import schemdraw
import schemdraw.elements as elm

To make a circuit diagram, use a context manager (with statement) on a schemdraw.Drawing. Then any schemdraw.elements.Element instances created within the with block added to the drawing:

with schemdraw.Drawing():
    elm.Resistor()
    elm.Capacitor()
    elm.Diode()
../_images/start_1_0.svg

New in version 0.18: The context manager keeps track of the active drawing, so that using drawing.add(element) or drawing += element is no longer necessary. These operators are still functional and are needed if drawing outside a with context manager:

with schemdraw.Drawing() as drawing:
    drawing += elm.Resistor()
    drawing += elm.Capacitor()
    drawing.add(elm.Diode())   # Same as `drawing +=`

Element placement and other properties and are set using a chained method interface, for example:

with schemdraw.Drawing():
    elm.Resistor().label('100KΩ')
    elm.Capacitor().down().label('0.1μF', loc='bottom')
    elm.Line().left()
    elm.Ground()
    elm.SourceV().up().label('10V')
../_images/start_2_0.svg

Methods up, down, left, right specify the drawing direction, and label adds text to the element. If not specified, elements reuse the same direction from the previous element, and begin where the previous element ended.

Using the with context manager is a convenience, letting the drawing be displayed and saved upon exiting the with block. Schematics may also be created simply by assinging a new Drawing instance, but this requires explicitly adding elements to the drawing with d.add or d +=`, and calling draw() and/or save() to show the drawing:

d = schemdraw.Drawing()
d += elm.Resistor()
...
d.draw()
d.save('my_circuit.svg')

For full details of placing and stylizing elements, see Placing Elements. and schemdraw.elements.Element.

In general, parameters that control what is drawn are passed to the element itself, and parameters that control how things are drawn are set using chained Element methods. For example, to make a polarized Capacitor, pass polar=True as an argument to Capacitor, but to change the Capacitor’s color, use the .color() method: elm.Capacitor(polar=True).color(‘red’).

Viewing the Drawing

Jupyter

When run in a Jupyter notebook, the schematic will be drawn to the cell output after the with block is exited. If your schematics pop up in an external window, and you are using the Matplotlib backend, set Matplotlib to inline mode before importing schemdraw:

%matplotlib inline

For best results when viewing circuits in the notebook, use a vector figure format, such as svg before importing schemdraw:

%config InlineBackend.figure_format = 'svg'

Python Scripts and GUI/Web apps

If run as a Python script, the schematic will be opened in a pop-up window after the with block exits. Add the show=False option when creating the Drawing to suppress the window from appearing.

with schemdraw.Drawing(show=False) as d:
    ...

The raw image data as a bytes array can be obtained by calling .get_imagedata() with the after the with block exits. This can be useful for integrating schemdraw into an existing GUI or web application.

with schemdraw.Drawing() as drawing:
    ...
image_bytes = drawing.get_imagedata('svg')

Headless Servers

When running on a server, sometimes there is no display available. The code may attempt to open the GUI preview window and fail. In these cases, try setting the Matplotlib backend to a non-GUI option. Before importing schemdraw, add these lines to use the Agg backend which does not have a GUI. Then get the drawing using d.get_imagedata(), or d.save() to get the image.

import matplotlib
matplotlib.use('Agg') # Set Matplotlib's backend here

Alternatively, use Schemdraw’s SVG backend (see Backends).

Saving Drawings

To save the schematic to a file, add the file parameter when setting up the Drawing. The image type is determined from the file extension. Options include svg, eps, png, pdf, and jpg when using the Matplotlib backend, and svg when using the SVG backend. A vector format such as svg is recommended for best image quality.

with schemdraw.Drawing(file='my_circuit.svg') as d:
    ...

The Drawing may also be saved using with the schemdraw.Drawing.save() method.