The app module

The app module defines three classes: Application, Canvas, and Timer. On loading, vispy creates a default Application instance which can be used via functions in the module’s namespace., call_reuse=True)[source]

Get/create the default Application object

It is safe to call this function multiple times, as long as backend_name is None or matches the already selected backend.

backend_name : str | None

The name of the backend application to use. If not specified, Vispy tries to select a backend automatically. See vispy.use() for details.

call_reuse : bool

Whether to call the backend’s reuse() function (True by default). Not implemented by default, but some backends need it. For example, the notebook backends need to inject some JavaScript in a notebook as soon as use_app() is called.[source]

Create the native application.[source]

Enter the native GUI event loop.[source]

Quit the native GUI event loop.[source]

Process all pending GUI events

If the mainloop is not running, this should be done regularly to keep the visualization interactive and to keep the event system going.


Representation of the vispy application

This wraps a native GUI application instance. Vispy has a default instance of this class that can be created/obtained via

backend_name : str | None

The name of the backend application to use. If not specified, Vispy tries to select a backend automatically. See vispy.use() for details.


Upon creating an Application object, a backend is selected, but the native backend application object is only created when create() is called or native is used. The Canvas and Timer do this automatically.


The module object that defines the backend.


The name of the GUI backend that this app wraps.


Create the native application.


Determine if the user requested interactive mode.


Determine if the user is executing in a Jupyter Notebook


The native GUI application instance.


Process all pending GUI events. If the mainloop is not running, this should be done regularly to keep the visualization interactive and to keep the event system going.


Quit the native GUI event loop.


Called when the application is reused in an interactive session. This allow the backend to do stuff in the client when use_app() is called multiple times by the user. For example, the notebook backends need to inject JavaScript code as soon as use_app() is called.

run(self, allow_interactive=True)[source]

Enter the native GUI event loop.

allow_interactive : bool

Is the application allowed to handle interactive mode for console terminals? By default, typing python -i results in an interactive shell that also regularly calls the VisPy event loop. In this specific case, the run() function will terminate immediately and rely on the interpreter’s input loop to be run after script execution.

sleep(self, duration_sec)[source]

Sleep for the given duration in seconds.

This is used to reduce CPU stress when VisPy is run in interactive mode. see for details

duration_sec: float

Time to sleep in seconds

class'VisPy canvas', size=(800, 600), position=None, show=False, autoswap=True, app=None, create_native=True, vsync=False, resizable=True, decorate=True, fullscreen=False, config=None, shared=None, keys=None, parent=None, dpi=None, always_on_top=False, px_scale=1)[source]

Representation of a GUI element with an OpenGL context

title : str

The widget title

size : (width, height)

The size of the window.

position : (x, y)

The position of the window in screen coordinates.

show : bool

Whether to show the widget immediately. Default False.

autoswap : bool

Whether to swap the buffers automatically after a draw event. Default True. If True, the swap_buffers Canvas method will be called last (by default) by the canvas.draw event handler.

app : Application | str

Give vispy Application instance to use as a backend. ( is used by default.) If str, then an application using the chosen backend (e.g., ‘pyglet’) will be created. Note the canvas application can be accessed at

create_native : bool

Whether to create the widget immediately. Default True.

vsync : bool

Enable vertical synchronization.

resizable : bool

Allow the window to be resized.

decorate : bool

Decorate the window. Default True.

fullscreen : bool | int

If False, windowed mode is used (default). If True, the default monitor is used. If int, the given monitor number is used.

config : dict

A dict with OpenGL configuration options, which is combined with the default configuration options and used to initialize the context. See canvas.context.config for possible options.

shared : Canvas | GLContext | None

An existing canvas or context to share OpenGL objects with.

keys : str | dict | None

Default key mapping to use. If ‘interactive’, escape and F11 will close the canvas and toggle full-screen mode, respectively. If dict, maps keys to functions. If dict values are strings, they are assumed to be Canvas methods, otherwise they should be callable.

parent : widget-object

The parent widget if this makes sense for the used backend.

dpi : float | None

Resolution in dots-per-inch to use for the canvas. If dpi is None, then the value will be determined by querying the global config first, and then the operating system.

always_on_top : bool

If True, try to create the window in always-on-top mode.

px_scale : int > 0

A scale factor to apply between logical and physical pixels in addition to the actual scale factor determined by the backend. This option allows the scale factor to be adjusted for testing.


The Canvas receives the following events:

  • initialize
  • resize
  • draw
  • mouse_press
  • mouse_release
  • mouse_double_click
  • mouse_move
  • mouse_wheel
  • key_press
  • key_release
  • stylus
  • touch
  • close

The ordering of the mouse_double_click, mouse_press, and mouse_release events are not guaranteed to be consistent between backends. Only certain backends natively support double-clicking (currently Qt and WX); on other backends, they are detected manually with a fixed time delay. This can cause problems with accessibility, as increasing the OS detection time or using a dedicated double-click button will not be respected.


The vispy Application instance on which this Canvas is based.


Close the canvas


This will usually destroy the GL context. For Qt, the context (and widget) will be destroyed only if the widget is top-level. To avoid having the widget destroyed (more like standard Qt behavior), consider making the widget a sub-widget.

connect(self, fun)[source]

Connect a function to an event

The name of the function should be on_X, with X the name of the event (e.g. ‘on_draw’).

This method is typically used as a decorator on a function definition for an event handler.

fun : callable

The function.


The OpenGL context of the native widget

It gives access to OpenGL functions to call on this canvas object, and to the shared context namespace.


Create the native widget if not already done so. If the widget is already created, this function does nothing.


The physical resolution of the canvas in dots per inch.


The fps of canvas/window, as the rate that events.draw is emitted

measure_fps(self, window=1, callback='%1.1f FPS')[source]

Measure the current FPS

Sets the update window, connects the draw event to update_fps and sets the callback function.

window : float

The time-window (in seconds) to calculate FPS. Default 1.0.

callback : function | str

The function to call with the float FPS value, or the string to be formatted with the fps value and then printed. The default is '%1.1f FPS'. If callback evaluates to False, the FPS measurement is stopped.


The native widget object on which this Canvas is based.


The physical size of the canvas/window, which may differ from the size property on backends that expose HiDPI


The ratio between the number of logical pixels, or ‘points’, and the physical pixels on the device. In most cases this will be 1.0, but on certain backends this will be greater than 1. This should be used as a scaling factor when writing your own visualisations with gloo (make a copy and multiply all your logical pixel values by it). When writing Visuals or SceneGraph visualisations, this value is exposed as TransformSystem.px_scale.


The position of canvas/window relative to screen


Render the canvas to an offscreen buffer and return the image array.

image : array

Numpy array of type ubyte and shape (h, w, 4). Index [0, 0] is the upper-left corner of the rendered region.

set_current(self, event=None)[source]

Make this the active GL canvas

event : None

Not used.

show(self, visible=True, run=False)[source]

Show or hide the canvas

visible : bool

Make the canvas visible.

run : bool

Run the backend event loop.


The size of canvas/window

swap_buffers(self, event=None)[source]

Swap GL buffers such that the offscreen buffer becomes visible

event : None

Not used.


The title of canvas/window

update(self, event=None)[source]

Inform the backend that the Canvas needs to be redrawn

event : None

Not used.

class'auto', connect=None, iterations=-1, start=False, app=None)[source]

Timer used to schedule events in the future or on a repeating schedule

interval : float | ‘auto’

Time between events in seconds. The default is ‘auto’, which attempts to find the interval that matches the refresh rate of the current monitor. Currently this is simply 1/60.

connect : function | None

The function to call.

iterations : int

Number of iterations. Can be -1 for infinite.

start : bool

Whether to start the timer.

app : instance of

The application to attach the timer to.


The vispy Application instance on which this Timer is based.

connect(self, callback)[source]

Alias for

disconnect(self, callback=None)[source]

Alias for


The native timer on which this Timer is based.

start(self, interval=None, iterations=None)[source]

Start the timer.

A timeout event will be generated every interval seconds. If interval is None, then self.interval will be used.

If iterations is specified, the timer will stop after emitting that number of events. If unspecified, then the previous value of self.iterations will be used. If the value is negative, then the timer will continue running until stop() is called.

If the timer is already running when this function is called, nothing happens (timer continues running as it did previously, without changing the interval, number of iterations, or emitting a timer start event).


Stop the timer.