image#

Image directive inserts image block to the text.

Image syntax#

Basically, you need only to specify a file to display in the image:: directive argument (please note the space after ::). Without options, image:: directive displays image as-is, i.e. in original size.

1.. image:: /img/banana.png
../_images/banana.png

Setting image width#

To change displayed image width, use :width: option. Modifying the width, also changes its height to keep the image’s width : height aspect ratio.

You can enter desired value either as length unit (e.g., px, em), or as percentage of available width (e.g, 50%).

1.. image:: /img/rocket.png
2   :width: 50%
../_images/rocket.png

Note

For example, in the HTML output the file is not actually resized. New dimensions are modified just in the browser by applying CSS style like width: 50%;.

Setting image height#

To change displayed image height, use :height: option. Modifying the height, also changes its width to keep the image’s width : height aspect ratio.

You must enter desired value as length unit (e.g., px, em). Values without a unit (e.g., 50) are px for HTML output (e.g., 50px).

1.. image:: /img/pumpkin.png
2   :height: 250px
../_images/pumpkin.png

Caution

Specifying percentages causes a warning similar to the following error:

WARNING: Error in "image" directive: invalid option value: (option: "height"; value: '50%') not a positive measure of one of the following units: "em" "ex" "px" "in" "cm" "mm" "pt" "pc" "".

Don’t maintain aspect ration#

If you specify either width or height, image will maintain its aspect ration. To turn it off, set both the :width: and :height: manually.

1.. image:: /img/banana.png
2   :width: 150px
3   :height: 250px
../_images/banana.png

Scaling images#

Instead of setting width, height, or both, you might want to scale the image based on its original dimensions.

For example, the image rocket.png has 1272x920 pixels. Setting :scale: 25% will set its width to 318px and height to 230px.

1.. image:: /img/rocket.png
2   :scale: 25%
../_images/rocket.png

Image alignment#

With :align: option the image will float and have the text flow (wrap) around it. Possible values are left, right, and center.

 1.. image:: /img/small-banana.png
 2
 3Dolor occaecat tempor nostrud enim velit laborum anim. Ut veniam fugiat consectetur ea. Fugiat commodo elit reprehenderit non pariatur officia velit dolore consectetur minim irure ad ex.
 4
 5.. image:: /img/small-banana.png
 6   :align: left
 7
 8Consectetur cillum ipsum laborum nisi id. Enim sunt fugiat eiusmod commodo proident culpa. Sit culpa deserunt cupidatat reprehenderit ex voluptate excepteur consectetur do. Proident est veniam occaecat reprehenderit occaecat Lorem eu. Sunt ad nisi velit tempor proident nulla exercitation voluptate exercitation.
 9
10.. image:: /img/small-banana.png
11   :align: right
12
13Do aliqua quis non fugiat reprehenderit ut veniam nulla qui quis proident consectetur dolor. Aliqua duis laboris minim nisi occaecat tempor dolor et consectetur voluptate. Nulla nostrud fugiat occaecat nostrud qui labore duis nisi aute. Sint pariatur qui incididunt minim.
14
15.. image:: /img/small-banana.png
16   :align: center
17
18Do aliqua quis non fugiat reprehenderit ut veniam nulla qui quis proident consectetur dolor.Deserunt nisi quis amet veniam mollit adipisicing adipisicing fugiat ad dolor.
../_images/small-banana.png

Dolor occaecat tempor nostrud enim velit laborum anim. Ut veniam fugiat consectetur ea. Fugiat commodo elit reprehenderit non pariatur officia velit dolore consectetur minim irure ad ex.

../_images/small-banana.png

Consectetur cillum ipsum laborum nisi id. Enim sunt fugiat eiusmod commodo proident culpa. Sit culpa deserunt cupidatat reprehenderit ex voluptate excepteur consectetur do. Proident est veniam occaecat reprehenderit occaecat Lorem eu. Sunt ad nisi velit tempor proident nulla exercitation voluptate exercitation.

../_images/small-banana.png

Do aliqua quis non fugiat reprehenderit ut veniam nulla qui quis proident consectetur dolor. Aliqua duis laboris minim nisi occaecat tempor dolor et consectetur voluptate. Nulla nostrud fugiat occaecat nostrud qui labore duis nisi aute. Sint pariatur qui incididunt minim.

../_images/small-banana.png

Do aliqua quis non fugiat reprehenderit ut veniam nulla qui quis proident consectetur dolor.Deserunt nisi quis amet veniam mollit adipisicing adipisicing fugiat ad dolor.

Caution

The exact behavior and appearance depends on output format and theme. For example, in the most HTML themes, the center value center the image but don’t float (wrap).