--watchfunctionality not yet implemented.
This CLI utility simplifies use of LaTeX by streamlining compilation and providing easy-to-use watch/rebuild functionality.
It works for basic LaTeX projects and outputs only the resultant PDF file, using the standard set of commands:
pdflatex myfile.tex bibtex myfile pdflatex myfile.tex pdflatex myfile.tex
It skips the
bibtex command if no
.bib file is supplied or found in the project's root.
This is the only LaTeX use case the author has had to deal with so far, which is his attempt at explaining why that's all that's supported. If you've other use cases, such as needing to deal with postscript or other output files, please contact the author and/or possibly consider contributing some code.
npm install -g texgo
Navigate to the root directory for your LaTeX project and:
This'll try finding the main
run the compilation and leave you with only the output
Optionally configure with
.texgorc to version control and share,
then all anybody needs to do is
Consider bringing Docker into the mix, so nobody even needs to worry about installing LaTeX!
texgo --help texgo -h
The help commands provide a useful, quick summary of usage. This README, however, is a more thorough and explained form of documentation.
Each of the options covered below can be provided via configuration,
on a global, per-project or mixed basis,
allowing you to simply execute
texgo once configured.
This package assumes any required LaTeX commands and resources are available to the user executing the command, unless you decide to use Docker (as described in the Using Docker section below).
Enter the root directory of your LaTeX project and execute one of:
texgo # to simply compile the document once - # works without extra parameters if there's only one `.tex` file in the root directory. texgo main.tex # to specify which is the main `.tex` file. texgo --watch # to compile once, and then watch for changes such to compile responsively. texgo -w # is the same as above. texgo -w main.tex # is again needed if there are multiple `.tex` files to choose from.
.bib file must also be specified if more than one happen to be present in the root directory:
texgo --bib main.bib texgo -w -b main.bib main.tex # is the same as above, # but also watching and specifying a main `.tex` file.
You can also execute TeXgo from elsewhere by specifying the root directory explicitly:
texgo --dir ../myproject texgo -d ../myproject -w # is the same as above, with watching. # You mustn't prefix the start `.tex` file if there is one - # it will be located relative to the specified root directory. texgo -d ../myproject -w main.tex
--watchwill fail without
--forceif the output file already exists on its first compilation - after the first compilation it will be fine to overwrite itself without
The output PDF file will by default be written to a file in the root directory,
with the same name as the main
.tex file, but of course with
texgo --output ../output/myproject.pdf texgo -o ../output/myproject.pdf # which is the same as above - # the invocation will fail because it will _not_ overwrite that file. texgo --force -o ../output/myproject.pdf # however, will overwrite an existing output file. texgo -f -o ../output/myproject.pdf -w main.tex # is the same as above, with watching and a main file.
TeXgo can be used without having LaTeX installed on the host system with thanks to Docker.
Basically, instead of attempting to run the LaTeX compilation scripts on the host system, TeXgo can use Docker to pull down a Docker image with LaTeX installed, and use the commands within that instead.
This shifts the requirement from having LaTeX installed and available on your system, to having Docker installed and available on your system. Docker would then pull down a LaTeX image, which takes time. Once pulled, future invocations would of course operate much faster.
The main benefit here is portability.
If working with a complex LaTeX build which involves many additional packages (outside of
other users may have trouble compiling your document.
If you're able to shift that complexity into a Dockerfile,
then anybody can simply type
texgo and know they're getting exactly the same results as you.
If you can successfully run this command (without
then you should be good to go:
docker run --rm hello-world
Use TeXgo with Docker:
# Use the default image: `tianon/latex:latest`. texgo --docker texgo -D # is the same as above. # Specify your own Docker image. # `myImages/latex:lite` is fictional - replace with yours. texgo --docker --image myImages/latex:lite texgo -D -I myImages/latex:lite # is the same as above.
About the Docker image..
The default Docker image used is
because it's dead simple and contains
texlive-full, which should work for almost everybody.
It also happens to currently (2016/07/04) be the most popular LaTeX repository.
texlive-full isn't small, so that image weighs in at ~4Gb...
For that reason, it may be wise to
docker pull tianon/latex:latest beforehand
pull subcommand provides more information -
you might think something's going wrong when
run tries to pull it
(because it doesn't show a progress bar)).
Alternatively, you can roll your own, more light-weight LaTeX Dockerfile
and only add in the things you need to get your project compiling.
That Dockerfile can operate locally, as long as it's tagged appropriately.
blang/latex-docker for partial inspiration.
To avoid having to specify parameters like
(and possibly even
--force if you're so willing) many times,
this utility supports provision of configuration files as per the
This can be considered as the default configuration, which acts as if no parameters were provided:
dir= main= bib= output= force= docker= image=
Here's an example configuration,
which can be automatically loaded if written a file named
.texgorc in the current directory,
wherever that may be:
dir=../myproject main=main.tex bib=main.bib output=../output/myproject.pdf ; Any non-blank value will enable the force option. force=1
Now you can simply execute
and your configuration will be picked up and used.
As briefly mentioned, this worked because a file named
.texgorc was present
in the directory that the
texgo command was being executed.
rc package describes many other ways to provide such a configuration file
~/.config/texgo or specified via
- Any options specified as part of the command will take precedence over those found in configuration files.
- Configuration is loaded when the command is initially executed,
so it won't be automatically updated if changed during a
If you wanted to use Docker across your system,
instead of installing LaTeX yourself,
you could use
~/.config/texgo to avoid typing
--image many times:
docker=1 ; If you need to use a custom image. image=myImages/latex:lite
If you had a particular project which had a custom LaTeX installation/configuration,
you could try to create a Dockerfile and replicate that installation,
and then include that in the project's
This means you could reformat your computer or come back in a year's time,
and still get up and running without missing a beat,
or share the project with someone else
and not worry about them not having correct dependencies, or configuring TeXgo -
all they'd have to do is type
Caveats and Assumptions
- The set of executed compilation commands is not modifiable.
- Does not support bibliography packages that require commands other than
- If a
--diris specified which is not the current directory, it will not be checked for RC files.
- If LaTeX tries to relatively refer to files outside of the root directory of the project, it will not find those files. This is because the root directory is copied to and used from a temporary location.
- Only supports output of the single resultant PDF.
- The compiled PDF is expected to have the same filename as the main
.texfile, but of course with the appropriate file extension.