Add Text to Images With Linux 'convert' Command




This instructable will show you how to add text to an image using the convert command in Linux. One valuable use of this is the placing of a caption on an image for documentation. Another use would be the placing of a time stamp on an image that gets generated automatically by a webcam.

There are many convert options that you can make use of in placing text on the image. You can choose the starting point for the text (via a height/width coordinate), the fill color of the text, the point size of the text, and the font used. This instructable will show you how to do all this.

The major catch with this instructable is that you have to do all this in the Linux operating system. I'm not aware of a utility such as convert in Microsoft Windows but who ever does anything with a command line in Windows? This instructable is more aimed at Linux users who want to get more out of their computer. If you are a Windows user and are still tempted to read this instructable, you may be tempted to download and install Linux. I may write an instructable on how to do this at a later date but if you want to pursue this on your own, you can go to and start the process. You can turn your computer into a dual-boot machine (I'd really recommend that you install a second hard disk in your machine -- any size will do). BTW, Linux is FREE, along with everything available to it. Also, so far, it is invulnerable to viruses.

Teacher Notes

Teachers! Did you use this instructable in your classroom?
Add a Teacher Note to share how you incorporated it into your lesson.

Step 1: The Linux 'convert' Utility

To perform the task of adding a label to an image, we will be working entirely within a Linux terminal window. Windows calls this a command window but it is rarely used in Windows except by oldtimers who remember it from the DOS days. Linux users make heavy use of it.

First of all, bring up a terminal window. With Ubuntu Linux, you do this by selecting Applications->Terminal. A window will open up with a command line prompt. It will put you at your home directory.

Let's assume that the image you want to play with is in an "images" subdirectory. To get to that subdirectory, type "cd images". Issue the comman "ls" to see what files are there. In my case, I want to work with a file called "sunset1.jpg".

You also want to make sure that the convert command is available on your system. One way to do this is to issue the command "which convert". If it is available, its location will be printed to the screen. In my case, it is at "/usr/bin/convert". Another way to find out if it is available, just issue the command "convert" at the command line. If it is there, a long description of the command will be printed out with all the options available. If it is not there, you will see "convert: command not found". Let's assume that it is available.

If you issue the bare command "convert" you can see that it is a very powerful tool with many capabilities. A more complete description of the convert command can be found at:

For our purposes, we only want to use the "-draw" argument to write the caption to the photo.

Step 2: Adding a Caption

My original image will be a file called sunset1.jpg. This is a photo that I took on a recent trip to Egypt and Jordan
(You can see all the photos at ).
I will keep the original image in place and save changes to new filenames for safety sake.

The original image is a scaled down version of a much larger image that was a 7 megapixel image. I used another capability of the "convert" command to resize it a smaller version for this instructable. This image is 640x480. That means that it is 640 pixels wide and 480 pixels tall. We will use this information to determine where we want to place the caption.

Here is a command that produces sunset2.jpg:

convert -pointsize 20 -fill yellow -draw 'text 270,460 "Sunset over the Nile" ' sunset1.jpg sunset2.jpg

-pointsize 20: this is the size of the letter (there are 72 points per inch)

-fill yellow: this is the fill color of the text

-draw 'text 270,460 "Sunset over the Nile" ': start 270 pixels from the left and 460 pixels from the top

sunset1.jpg sunset2.jpg: using the first file as a starting point, write out to the second file

There is a wide range of color names that you can specify. If you enter the command "showrgb", you will see the long list of color names available (isn't Linux great?).

The -draw argument has to be treated carefully. After -draw you start the argument with a single quote. You then put put the horizontal and vertical coordinates of where you want to the text to start. If you put a coordinate that is larger than either dimension, the text won't show up. Finally, you put the caption in double quotes. Make sure to end the whole argument with a closing single quote.

The two last arguments (sunset1.jpg sunset2.jpg) indicate that you want to use sunset1.jpg as the starting point and want to write the results to sunset2.jpg. If you had put sunset1.jpg sunset1.jpg, it would modify the original copy of the image.

Once you issue this command, you should see the file sunset2.jpg show up in your photos directory. If you want to, you can put as many chunks of text as you want on the image. Just keep adding them to sunset2.jpg file.

Note that there is a font argument that you can also use. For example, you can insert "-font helvetica" after the "convert". Your Linux system has a whole library of fonts. Mine are located at "/var/lib/defoma/gs.d/dirs/fonts/". I count over 170 of them there. Instead of using "-font helvetica" I might use something like "-font /var/lib/defoma/gs.d/dirs/fonts/Loma-BoldOblique.ttf". These are fun to play with.

You can can use the Coordinate Map for the approximate horizontal and vertical coordinates that would apply to an image that is 640x480. The markup on this image was created using the convert utility.

Step 3: Automating the Labeling of Images

You have seen how you manually add a caption to an image from the command line. This works fine if you just have a few photos to work with but it can be pretty tedious to work this way. If you have a whole lot of images to process, you might want to make use of some sort of scripting language in Linux. One possibility is to use a shell script. What I use is a scripting language called Perl. This is what I use for all kinds of CGI scripts on the web. Other possibilities are Java, C++, PHP, and Python. Whatever you use, you have to be able to create a command line string and the shell out to execute it.

One way that I make use of this is where I automatically put the timestamp on an image that my webcam generates once a minute. In a Perl script I formulate the current timestamp (date and time) and then overlay it on the current image. I also put my website address on the photo. You can see that the attached image was taken on February 2 at 13:07. I have a script on my computer that runs once a minute. It grabs the image from the webcam, inserts the website name and timestamp, and then uploads it to my website. You MAY be able to see this in action at I say "may" because this only happens when my computer is turned on. I don't leave it on overnight or when I am away.

If I wanted to label a whole directory of images, I would create a Perl script to do it. One way to do this is to create a text file that has the whole list of images in the directory, one per line. Following the image name on each line would be the text of the caption. I would create a loop that would take the label and apply it to the image. Of course, there would be a problem of getting the label centered horizontally. I would probably have to calculate the actual width of the caption and then adjust the horizontal argument.

1 Person Made This Project!


  • Made with Math Contest

    Made with Math Contest
  • Multi-Discipline Contest

    Multi-Discipline Contest
  • Robotics Contest

    Robotics Contest

21 Discussions

Fernando Melo Medeiros

Question 4 months ago

I use Peppermint operatng system. I've installed "lucida calligraphy", "comic sans ms" and verdana. Now when using "convert" I don't have access to them. When I try to change the font, "convert" doesn't accept. Then I write "-font verdana" and nothing happens but a lot of information saying that it impossible for me to use "verdana". And I don't even know where verdana is. I've tried to find it but I haven't succeeded.

1 answer
rhackenbFernando Melo Medeiros

Answer 4 months ago

I'm afraid that I have not had much experience in the use of fonts with this application.
To see the fonts it knows about issue the following command in a terminal:
convert -list font
This will give you a very long list of the fonts it can handle. You can add a grep to the command such as
convert -list font | grep Comic
This does not find anything with Comic (or comic).
Maybe you can find a font that is closest to what you are looking for.


Question 1 year ago on Introduction

how to add caption to an image using text editor


3 years ago

"convert" is an usful information it would helpful for my site


3 years ago

for these linux users "convert " is an usul inforamtion for studying, for more online training program visit


3 years ago

For Linux users, "Convert" is a good comment to add text to images. We are also in exploring Linux OS and sharing with our students. If anyone is looking for building skills in Linux administration, then refer this link.


4 years ago on Introduction

Thank you! Very useful!

One way that I make use of this is where I automatically put the
timestamp on an image that my webcam generates once a minute. In a Perl

There is also an Image::Magick perl module that works the same on any platform.

If you add captions automatically, you might find that in some cases, the color of the text blends with a background. In this case, you might want to use the 3D captions technique:

convert -pointsize 20 -fill white -draw 'text 268,458 "Sunset over the Nile" ' -fill black -draw 'text 272,462 "Sunset over the Nile" ' -fill yellow -draw 'text 270,460 "Sunset over the Nile" ' sunset1.jpg sunset2.jpg

That way, there is always the chance that a white or black version of the text would be legible over the background color...


4 years ago on Introduction

how do i get a paragraph Text using terminal .. think my text has to be like

wish you

Happy New

and how do i get a good front..


Reply 8 years ago on Introduction

I'm thinking of switching to arch. anything I should know (yes, I know its simple, from a programmers point of view, I read the wiki some, I read the beginners guide, etc)?


Reply 10 years ago on Introduction

Blegh. Ubuntu is the easiest for new users, especially with it's very extensive documentation with fixes for essentially all problems you may come by.


Reply 10 years ago on Introduction

ubuntu has few times more problems than any other distro i tried ubuntu newbies come to me to ask for help with amont of problems way higher than other distros


Reply 10 years ago on Introduction

I have installed Ubuntu for several of my friends. One of them, a 75 year old who was having virus troubles with Windows, brags about his installation. The only time he has contacted me about a problem was after a major automatic upgrade, he was not able to print anymore. I told him to chose his printer instead of the default PDF target that Ubuntu mysteriously choses as the default. After he simply looked at his choices, the problem was solved. Ubuntu is an excellent installation and a great replacement for Windows for people who don't really do more than browse the web and check their web-based email. They don't even notice the difference. Of course, it's good for most everything else. Ubuntu is the best distribution I every found, mainly because of it's ability to install software from many sources.


Reply 10 years ago on Introduction

you should be lucky. enjoy ! i know ubuntu as a distro slower than windows xp (unless windows is infected or overloaded with crap) and one that creates problems every here and there and they come back after you allredy fixed them


Reply 10 years ago on Introduction

My experience is completely the opposite. I dual-boot machines and I always find Ubuntu to be faster than XP on the very same machine. I generally have no problems with ubuntu once I get stuff installed. I never see a problem get solved and then come back. The only real problem I ever have is when I don't automatically have drivers for things like Wi-Fi receivers. However, once the driver is installed, there are nor more problems with it. I installed Ubuntu on a 75 year old's machine. He is totally amazed by how fast the linux side runs compared to his XP side (I had totally wiped his XP and reinstalled it). He never calls me with problems. I've been using various distributions of Linux since the early 90's. Ubuntu is by far the best and most user-friendly. It now even performs major upgrades to the kernel without assistance from me.


8 years ago on Introduction

*almost everything is free

anyway, you should try phatch. it batch processes photos, and it has many capabilities. and the best part: its for linux only! muahaha