I have created my own LaTeX template and use a custom class for this purpose. I developed the template on a Windows machine using TeX Live 2020 and recently compiled a copy of the project on my Mac. However, on the Mac with MacTeX 2020, errors occurred that I could trace back to the options not working. Further attempts to pinpoint the problem showed that the options only don't work if the class is in a subfolder. If it is in the root directory, then it works fine. I also noticed that the error only occurs when the native LaTeX compilers are used. In Texpad the error does not occur.

The following files should illustrate the errors as a minimal example. For all those who can't run it themselves due to system requirements, I show the outputs of the respective document generation steps.

testclass.cls and testfolder/testclass.cls









\documentclass[optionFalse]{testclass} % works
% \documentclass[optionFalse]{testfolder/testclass} % does not work

   \texttt{testOption} is set to \texttt{\printtestresult}

Project structure

├── test.tex
├── testclass.cls
└── testfolder
    └── testclass.cls

When creating the document with \documentclass[optionFalse]{testclass} I get the following outputs:

  • Windows:
    • testOption is set to false
  • Mac:
    • Texpad:
      • testOption is set to false
    • native compiler:
      • testOption is set to false

If, however, I use the nested class \documentclass[optionFalse]{testfolder/testclass}, the following happens:

  • Windows (native):
    • testOption is set to false
  • Mac
    • Texpad:
      • testOption is set to false
    • native compiler:
      • testOption is set to true

Feel free to ask for more information if I have forgotten anything important. I find it quite difficult to explain this bug clearly, as it is not really tangible for me. What I can say, though, is that the same bug occurs on a friend's brand new Mac, which has a fresh MaxTeX installation on it. So it seems not to be a problem with my distribution.

  • \documentclass doesn't take a path but only the name provided by the class itself. In order to let latex find your class file, you have to either move the file to your local texmf-tree or add the subdirectory to your path (you can use the TEXINPUTS variable for that)
    – DG'
    Dec 16, 2020 at 21:50
  • 2
    this should be resolved in the latex version, see e.g. github.com/latex3/latex2e/issues/422 Dec 16, 2020 at 21:51
  • @DG' I understand, but as already stated in the issue posted by Ulrike, I, too, want to have a portable template that I can easily share with colleagues, thus I'd prefer not to move the .cls file into the texmf directory. As it has worked some time ago (in another but similar template) and also works on my Windows machine, I guess that it should work as expected by me, even if it's not the recommended way to go.
    – Sam
    Dec 16, 2020 at 22:53
  • @UlrikeFischer Thanks for that resource. I see that this should be fixed in the hotfix gh422, but how can I install this hotfix on my machine? Running tlmgr update --all does not seem to work.
    – Sam
    Dec 16, 2020 at 22:55
  • 1
    Note that we'll fix if for compatibility but the use was never really supported, and by design gives a warning that testfolder/testclass does not match testclass you can make it work without warning in all versions of latex by using \documentclass{testclass} and putting testclass.cls in the current directory if you don't want to put it in your tex input tree. Dec 17, 2020 at 0:15

1 Answer 1


As pointed out in comments by members of the LaTeX Project team, calling classes from within subfolders is not an intentionally supported functionality. In the course of the update of LaTeX to version 2020-10-01, this functionality was lost. A GitHub issue pointed out this problem back on October 31, and a bugfix was merged into hotfix gh422 for compatibility. However, since this hotfix is not yet available via an update of LaTeX at the time of this post, I tried a workaround that was also recommended in said GitHub issue.

It actually works fine to tell LaTeX a folder within a document where it can search for files. The advantage of this is that you don't have to set this specific folder via TEXINPUTS in your PATH variable for each document. All you have to do is execute the following snippet as the first code in the document so that LaTeX knows the subfolder that contains the class.


Using my initial example, the correct use looks like the following:

Change test.tex to:



   \texttt{testOption} is set to \texttt{\printtestresult}

With this, LaTeX will search also in the ./testfolder directory for a class named testclass.

  • +1 sorry for the delay in getting out the update (mostly related to real world issues, not the tex coding) Dec 17, 2020 at 9:45

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .