YouTube and Vimeo

The youtube directive embeds content from directly in a page.

The vimeo directive embeds content from directly in a page.


The general format of the youtube directive is:

.. youtube:: youtube video id

The general format of the vimeo directive is:

.. vimeo:: vimeo video id

Both the vimeo and youtube directives take the same options (with one exception).

Required Arguments


This must be the ID defined for this video by YouTube or Vimeo, respectively.

content area

Neither the vimeo or youtube directive use a content area.

Optional Arguments


Enumeration. Define video horizontal alignment.

One of left, right, or center is allowed. The default is left.


String. Define a runestone id for this video. YouTube only.

The default divid is the YouTube video id.

This is provides backward compatibility when converting HTML5 hosted videos to the YouTube platform. Or use this if you want to use a different descriptor to reference rather than the YouTube video id.


Integer. Define video height in pixels. Default height is 281 pixels.


Enumeration. Define default transport.

One of http or https is allowed. The default is http.


Integer. Define video width in pixels. Default width is 500 pixels.

Languages supported


Sphinx configuration options

No directive specific configuration options exist.



Known limitations

The ID can only include the video ID. Adding a time as in &t=3m35s or &start=90s breaks the video.

Can’t loop video or link to

No way to enable closed captioning on by default.


.. youtube:: anwy2MPT5RE
    :height: 315
    :width: 560
    :align: left
You have attempted of activities on this page