The docopt package

[Tags: library, mit]

Docopt parses command-line interface usage text that adheres to a familiar syntax, and from it builds a command-line argument parser that will ensure your program is invoked correctly with the available options specified in the usage text. This allows the developer to write a usage text and get an argument parser for free.

[Skip to ReadMe]


Dependenciesbase (==4.*), containers, parsec (==3.1.*), template-haskell (>=2.7 && <3.0), th-lift (>=0.7 && <1.0) [details]
Copyright(c) 2013-2015 Ryan Artecona
AuthorRyan Artecona
Home page
Bug tracker
Source repositoryhead: git clone
UploadedFri Sep 11 14:16:09 UTC 2015 by ryanartecona
DistributionsNixOS:, Stackage:
Downloads1079 total (38 in last 30 days)
1 []
StatusDocs available [build log]
Last success reported on 2015-09-11 [all 1 reports]




template-haskellBuild with QuasiQuoter usage parsers, which requires Template HaskellEnabledManual

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info


Maintainers' corner

For package maintainers and hackage trustees

Readme for docopt-


A Haskell port of python's docopt.

Want a command-line interface without building a parser?

How about writing your help text first, and getting a parser for free!

Save your help text to a file (i.e. USAGE.txt):

  myprog cat <file>
  myprog echo [--caps] <string>

  -c, --caps    Caps-lock the echoed argument

Then, in your Myprog.hs:

{-# LANGUAGE QuasiQuotes #-}
import Control.Monad (when)
import Data.Char (toUpper)
import System.Environment (getArgs)
import System.Console.Docopt

patterns :: Docopt
patterns = [docoptFile|USAGE.txt|]

getArgOrExit = getArgOrExitWith patterns

main = do
  args <- parseArgsOrExit patterns =<< getArgs

  when (args `isPresent` (command "cat")) $ do
    file <- args `getArgOrExit` (argument "file")
    putStr =<< readFile file

  when (args `isPresent` (command "echo")) $ do
    let charTransform = if args `isPresent` (longOption "caps")
                          then toUpper
                          else id
    string <- args `getArgOrExit` (argument "string")
    putStrLn $ map charTransform string

That's it! No Template Haskell, no unreadable syntax, no learning yet another finicky API. Write the usage patterns you support, and docopt builds the appropriate option parser for you (internally using parsec). If your user invokes your program correctly, you query for the arguments they provided. If the arguments provided do not match a supported usage pattern, you guessed it: docopt automatically prints the help text and exits!


cabal sandbox init
cabal install docopt

API Reference

See the package on hackage

Help text format

Docopt only cares about 2 parts of your help text:

Usage Patterns

Option descriptions

Option descriptions establish:


Differences from reference python implementation: