man pages section 1: User Commands

Exit Print View

Updated: July 2014

scanimage (1)


scanimage - scan an image


scanimage    [-d|--device-name    dev]   [--format   format]
[-i|--icc-profile profile] [-L|--list-devices] [-f|--format-
ted-device-list  format]  [--batch [=format]] [--batch-start
start] [--batch-count count]  [--batch-increment  increment]
[--batch-double]     [--accept-md5-only]     [-p|--progress]
[-n|--dont-scan]  [-T|--test]   [-h|--help]   [-v|--verbose]
[-B|--buffersize] [-V|--version] [device-specific-options]


SANE Scanner Access Now Easy                         scanimage(1)

     scanimage - scan an image

     scanimage    [-d|--device-name    dev]   [--format   format]
     [-i|--icc-profile profile] [-L|--list-devices] [-f|--format-
     ted-device-list  format]  [--batch [=format]] [--batch-start
     start] [--batch-count count]  [--batch-increment  increment]
     [--batch-double]     [--accept-md5-only]     [-p|--progress]
     [-n|--dont-scan]  [-T|--test]   [-h|--help]   [-v|--verbose]
     [-B|--buffersize] [-V|--version] [device-specific-options]

     scanimage  is  a  command-line  interface  to  control image
     acquisition devices such as  flatbed  scanners  or  cameras.
     The  device  is  controlled via command-line options.  After
     command-line  processing,  scanimage  normally  proceeds  to
     acquire  an  image.   The  image data is written to standard
     output in one of the PNM (portable aNyMaP) formats (PBM  for
     black-and-white  images,  PGM  for grayscale images, and PPM
     for color images) or in TIFF (black-and-white, grayscale  or
     color).    scanimage   accesses  image  acquisition  devices
     through the SANE (Scanner Access Now Easy) interface and can
     thus  support any device for which there exists a SANE back-
     end (try apropos sane- to get a list of available backends).

     To get a list of devices:

       scanimage -L

     To scan with default settings to the file image.pnm:

       scanimage >image.pnm

     To scan 100x100 mm to the file image.tiff (-x and -y may not
     be available with all devices):

       scanimage -x 100 -y 100 --format=tiff >image.tiff

     To print all available options:

       scanimage -h

     Parameters are separated by a  blank  from  single-character
     options  (e.g.   -d epson) and by a "=" from multi-character
     options (e.g. --device-name=epson).

sane-backends 1.0.19 Last change: 03 Oct 2006                   1

SANE Scanner Access Now Easy                         scanimage(1)

     The -d or --device-name options must be followed by  a  SANE
     device-name  like `epson:/dev/sg0' or `hp:/dev/usbscanner0'.
     A (partial) list of available devices can be  obtained  with
     the --list-devices option (see below).  If no device-name is
     specified explicitly, scanimage reads a device-name from the
     environment  variable SANE_DEFAULT_DEVICE.  If this variable
     is not set, scanimage will attempt to open the first  avail-
     able device.

     The --format format option selects how image data is written
     to standard output.  format can be pnm or tiff.  If --format
     is not used, PNM is written.

     The  -i  or  --icc-profile  option is used to include an ICC
     profile into a TIFF file.

     The -L or --list-devices option requests a (partial) list of
     devices  that are available.  The list is not complete since
     some devices may be available, but are not listed in any  of
     the  configuration  files  (which  are  typically  stored in
     directory /etc/sane.d).  This is particularly the case  when
     accessing  scanners through the network.  If a device is not
     listed in a configuration file, the only way to access it is
     by  its full device name.  You may need to consult your sys-
     tem administrator to find out the names of such devices.

     The -f or --formatted-device-list option  works  similar  to
     --list-devices,  but  requires  a  format string.  scanimage
     replaces the placeholders %d %v %m %t  %i  with  the  device
     name,  vendor  name,  model  name, scanner type and an index
     number respectively. The command

          scanimage -f  scanner number %i  device  %d  is  a  %t,
          model %m, produced by %v

     will produce something like:

          scanner  number 0  device sharp:/dev/sg1 is  a  flatbed
          scanner, model JX250 SCSI, produced by SHARP

     The --batch* options provide the features for scanning docu-
     ments  using  document feeders.  --batch [format] is used to
     specify the format of the filename that each  page  will  be
     written  to.  Each page is written out to a single file.  If
     format is  not  specified,  the  default  of  out%d.pnm  (or
     out%d.tif  for --format tiff) will be used.  format is given
     as  a  printf  style  string  with  one  integer  parameter.
     --batch-start  start selects the page number to start naming
     files with. If this option is not given,  the  counter  will
     start  at  0.   --batch-count  count specifies the number of
     pages to attempt to scan.  If not given, scanimage will con-
     tinue  scanning until the scanner returns a state other than

sane-backends 1.0.19 Last change: 03 Oct 2006                   2

SANE Scanner Access Now Easy                         scanimage(1)

     OK.  Not all scanners with document feeders signal when  the
     ADF  is  empty,  use this command to work around them.  With
     --batch-increment increment you can change the  amount  that
     the  number  in  the  filename is incremented by.  Generally
     this is used when you are scanning double-sided documents on
     a  single-sided document feeder.  A specific command is pro-
     vided to aid this: --batch-double will automatically set the
     increment to 2.  --batch-prompt will ask for pressing RETURN
     before scanning a page. This can be used for scanning multi-
     ple pages without an automatic document feeder.

     The --accept-md5-only option only accepts user authorization
     requests that support MD5 security. The SANE network  daemon
     (saned) is capable of doing such requests. See saned(8).

     The -p or --progress option requests that scanimage prints a
     progress counter. It shows how much image data of  the  cur-
     rent  image  has already been received by scanimage (in per-

     The -n or --dont-scan option requests  that  scanimage  only
     sets  the  options provided by the user but doesn't actually
     perform a scan. This option can be used to e.g. turn off the
     scanner's lamp (if supported by the backend).

     The  -T  or --test option requests that scanimage performs a
     few simple sanity tests to make sure the  backend  works  as
     defined  by  the SANE API (in particular the sane_read func-
     tion is exercised by this test).

     The -h or --help  options  request  help  information.   The
     information  is printed on standard output and in this case,
     no attempt will be made to acquire an image.

     The -v or --verbose options increase the  verbosity  of  the
     operation of scanimage.  The option may be specified repeat-
     edly, each time increasing the verbosity level.

     The -B or --buffersize option changes the  input  buffersize
     that  scanimage  uses  from  default  32*1024  to  1024*1024

     The -V or --version option requests  that  scanimage  prints
     the program and package name, the version number of the SANE
     distribution that it came with and the version of the  back-
     end  that  it loads. Usually that's the dll backend. If more
     information about the version numbers of  the  backends  are
     necessary,  the  DEBUG  variable  for the dll backend can be
     used. Example: SANE_DEBUG_DLL=3 scanimage -L.

     As you might imagine, much of the power of  scanimage  comes
     from  the  fact that it can control any SANE backend.  Thus,

sane-backends 1.0.19 Last change: 03 Oct 2006                   3

SANE Scanner Access Now Easy                         scanimage(1)

     the exact set of command-line options depends on  the  capa-
     bilities  of  the selected device.  To see the options for a
     device named dev, invoke scanimage via a command-line of the

          scanimage --help --device-name dev

     The documentation for the device-specific options printed by
     --help is best explained with a few examples:

      -l 0..218mm [0]
         Top-left x position of scan area.

          The description above shows that option -l  expects  an
          option  value in the range from 0 to 218 mm.  The value
          in square brackets indicates that  the  current  option
          value  is  0 mm. Most backends provide similar geometry
          options for top-left y position (-t),  width  (-x)  and
          height of scan-area (-y).

      --brightness -100..100% [0]
         Controls the brightness of the acquired image.

          The  description  above  shows that option --brightness
          expects an option value in the range from -100  to  100
          percent.   The  value in square brackets indicates that
          the current option value is 0 percent.

         Set default values for enhancement controls.

          The description  above  shows  that  option  --default-
          enhancements has no option value.  It should be thought
          of as having an immediate effect at the  point  of  the
          command-line  at  which it appears.  For example, since
          this option resets the --brightness option, the option-
          pair   --brightness   50  --default-enhancements  would
          effectively be a no-op.

      --mode Lineart|Gray|Color [Gray]
         Selects the scan mode (e.g., lineart or color).

          The description above shows that option --mode  accepts
          an  argument  that  must be one of the strings Lineart,
          Gray, or Color.  The value in the square bracket  indi-
          cates  that  the  option is currently set to Gray.  For
          convenience, it is legal to abbreviate the string  val-
          ues  as  long as they remain unique.  Also, the case of
          the spelling doesn't matter.  For example, option  set-
          ting --mode col is identical to --mode Color.

sane-backends 1.0.19 Last change: 03 Oct 2006                   4

SANE Scanner Access Now Easy                         scanimage(1)

      --custom-gamma[=(yes|no)] [inactive]
         Determines whether a builtin or a custom gamma-table
         should be used.

          The  description above shows that option --custom-gamma
          expects either no option value, a "yes"  string,  or  a
          "no"  string.   Specifying  the option with no value is
          equivalent to specifying "yes".  The value  in  square-
          brackets  indicates  that  the  option is not currently
          active.  That is, attempting to set  the  option  would
          result  in  an  error  message.   The  set of available
          options typically depends  on  the  settings  of  other
          options.   For  example, the --custom-gamma table might
          be active only when a grayscale or color scan-mode  has
          been requested.

          Note that the --help option is processed only after all
          other options have been processed.  This makes it  pos-
          sible  to see the option settings for a particular mode
          by specifying the appropriate mode-options  along  with
          the --help option.  For example, the command-line:

          scanimage --help --mode color

          would print the option settings that are in effect when
          the color-mode is selected.

      --gamma-table 0..255,...
         Gamma-correction table.  In color mode this option
         equally affects the red, green, and blue channels
         simultaneously (i.e., it is an intensity gamma table).

          The description above shows that  option  --gamma-table
          expects zero or more values in the range 0 to 255.  For
          example,  a  legal  value  for  this  option  would  be
          "3,4,5,6,7,8,9,10,11,12".   Since  it's  cumbersome  to
          specify long vectors in this  form,  the  same  can  be
          expressed  by  the abbreviated form "[0]3-[9]12".  What
          this means is that the first vector element is  set  to
          3,  the  9-th  element  is  set to 12 and the values in
          between are interpolated linearly.  Of  course,  it  is
          possible to specify multiple such linear segments.  For
          example, "[0]3-[2]3-[6]7,[7]10-[9]6" is  equivalent  to
          "3,3,3,4,5,6,7,10,8,6".   The  program  gamma4scanimage
          can  be  used  to  generate  such  gamma  tables   (see
          gamma4scanimage(1) for details).

      --filename <string> [/tmp/input.ppm]
         The filename of the image to be loaded.

          The  description  above is an example of an option that
          takes an arbitrary string value (which happens to be  a

sane-backends 1.0.19 Last change: 03 Oct 2006                   5

SANE Scanner Access Now Easy                         scanimage(1)

          filename).   Again, the value in brackets show that the
          option is current set to the filename /tmp/input.ppm.

          The default device-name.

          This directory holds various configuration files.   For
          details, please refer to the manual pages listed below.

          This file contains lines of the form


          scanimage uses this information to answer  user  autho-
          rization  requests  automatically.  The  file must have
          0600 permissions or stricter. You should use this  file
          in  conjunction  with  the  --accept-md5-only option to
          avoid server-side attacks. The resource may contain any
          character but is limited to 127 characters.

     See   attributes(5)   for   descriptions  of  the  following

     |ATTRIBUTE TYPE |         ATTRIBUTE VALUE           |
     |Availability   | image/scanner/xsane/sane-backends |
     |Stability      | Uncommitted                       |
     sane(7),   gamma4scanimage(1),    xscanimage(1),    xcam(1),
     xsane(1),  scanadf(1),  sane-dll(5),  sane-net(5), " .}S 3 1
     "sane-backendname"" "(5)" "" "" "" ""

     David Mosberger, Andreas  Beck,  Gordon  Matzigkeit,  Caskey
     Dickson,  and  many others.  For questions and comments con-
     tact  the  sane-devel  mailinglist   (see   http://www.sane-

     For vector options, the help output currently has no indica-
     tion as to how many elements a vector-value should have.

sane-backends 1.0.19 Last change: 03 Oct 2006                   6

SANE Scanner Access Now Easy                         scanimage(1)

     This  software  was   built   from   source   available   at    The  original
     community  source  was  downloaded  from    ftp://ftp2.sane-

     Further information about this software can be found on  the
     open    source   community   website   at   http://www.sane-

sane-backends 1.0.19 Last change: 03 Oct 2006                   7