



  

PyLaTeX 1.3.0+0.g4839531 documentation

 [PyLaTeX](index.html#document-index) 

 stable

 

* [Library usage](index.html#document-usage)

* [Examples](index.html#document-examples)

* [API reference](index.html#document-api)

* [Frequently Asked Questions](index.html#document-faq)

* [Change Log](index.html#document-changelog)

* [How to contribute](index.html#document-contributing)

[PyLaTeX](index.html#document-index)

* [Docs](index.html#document-index) »

* PyLaTeX 1.3.0+0.g4839531 documentation

* [Edit on GitHub](https://github.com/JelteF/PyLaTeX/blob/80d9baefc66f011df93946c8f08784cfe816db79/docs/source/index.rst)

---

PyLaTeX[¶](#pylatex "Permalink to this headline")

=================================================

PyLaTeX is a Python library for creating and compiling LaTeX files. The goal of

this library is to be an easy, but extensible interface between Python and

LaTeX.

PyLaTeX has two quite different usages: generating full pdfs and generating

LaTeX snippets. Generating full pdfs is mostly useful when all the text that

pdf should contain is generated by python, for instance exporting the data from

a database. Snippets are useful when some text still needs to be written by

hand, but some stuff can be automatically generated, for instance writing a

report with a couple of matplotlib plots.

Installation[¶](#installation "Permalink to this headline")

-----------------------------------------------------------

PyLaTeX works on Python 2.7 and 3.3+ and it is simply installed using pip:

```

pip install pylatex

```

Some of the features require other libraries as well. This is mostly the case

when converting a datatype of that library to LaTeX. For instance, generating

LaTeX matrices requires Numpy. The dependencies for these extra features can

simply be installed like this:

```

pip install pylatex[matrices]

```

The features that require aditional libraries are:

* matrices

* matplotlib

* quantities

Code[¶](#code "Permalink to this headline")

-------------------------------------------

To see the some code in action, please take a look at the examples/full,

which generates the pdf below. To understand how the code works, please look at

the [Library usage](index.html#document-usage).

![_images/screenshot.png](_images/screenshot.png)

Support[¶](#support "Permalink to this headline")

-------------------------------------------------

This library is being developed in and for Python 3. Because of a conversion

script the current version also works in Python 2.7. For future versions, no

such promise will be made. Python 3 features that are useful but incompatible

with Python 2 will be used. If you find a bug for Python 2 and it is fixable

without ugly hacks feel free to send a pull request.

This library is developed for Linux. I have no intention to write fixes or test

for platform specific bugs with every update, especially since I have no other

operating systems to test it on. Pull requests that fix those issues are always

welcome though. Issues have been fixed for Windows and it seems that compiling

to pdf is currently working.

Contributing[¶](#contributing "Permalink to this headline")

-----------------------------------------------------------

Read the [How to contribute](index.html#document-contributing) page for tips and rules when you want to

contribute. To just see the source code, you should go to the [Github

repository](https://github.com/JelteF/PyLaTeX/).

### Library usage[¶](#library-usage "Permalink to this headline")

#### Understanding PyLaTeX[¶](#understanding-pylatex "Permalink to this headline")

PyLaTeX is structured around two main tasks: Generating LaTeX code, and

compiling LaTeX documents. The package is flexible, and can either work with

your pre-existing code or generate new code with its system of classes. In

turn, LaTeX code can be used to generate a document, or can be exported as-is.

#### The Classes[¶](#the-classes "Permalink to this headline")

PyLaTeX uses a set of classes to turn LaTeX document generation into a set of

pythonic components. For example, a `Document` might be comprised of

`Section` objects, which in turn might have `List` objects, `Figure`

objects, or custom `Command` objects.

Classes can be part of a single document, or can act as pieces on their own.

With the `dumps` method, most classes can return their

LaTeX-formatted code, and with the `generate\_tex` method, this

code can be written to a file.

##### Containers / Documents[¶](#containers-documents "Permalink to this headline")

A `Container` is an object that groups other LaTeX classes. Containers

function like lists; they can be indexed and appended to.

One of the most important container classes is the `Document` class.

Documents create a full LaTeX document that can create a PDF file with

`generate\_pdf` . Unless you are only generating LaTeX snippets, you will

likely want to enclose your code inside a Document.

Additionally, a number of `section` containers are available, which

correspond to the standard `\section` commands of LaTeX. As with documents,

these can be appended to. A `Section` can further include a `Subsection` or

a `Subsubsection` object.

##### Tables, Images, Math, etc.[¶](#tables-images-math-etc "Permalink to this headline")

PyLaTeX has a number of classes that are useful in generating

difficult-to-format LaTeX code. See the API documentation and code examples for

information on a specific environment.

##### Commands, Options, and Arguments[¶](#commands-options-and-arguments "Permalink to this headline")

Although PyLaTeX has implemented many useful commands, it is easy to create a

custom command with the `Command` class. Commands can be supplied with

`{}` arguments or `[]` options, with either a single option as a string, or

multiple options in a list.

Additionally, Options and Arguments can be placed in an `Options` object or a

`Arguments` object.

##### Formatting Strings[¶](#formatting-strings "Permalink to this headline")

A number of functions are available in `utils` that are helpful in formatting

text. For example, the functions `bold` and `italic` exist to format text

appropriately.

#### Extending PyLaTeX[¶](#extending-pylatex "Permalink to this headline")

Because of all the base classes supplied by PyLaTeX, it is very easy to extend

its support in LaTeX features. Just pick one of the existing (base) classes

that fits best and extend that with the needed functionality.

All LaTeX objects come from `LatexObject` , but it is probably more useful to

extend one of the other base subclasses, like `Environment` or

`CommandBase`. Consult the API documentation to see the variety of base

classes available for use.

#### Plain LaTeX Strings[¶](#plain-latex-strings "Permalink to this headline")

Although PyLaTeX contains classes and functions to make generating LaTeX

formatted text easy, at its core it is a nice wrapper around string

manipulations. This is why all of them also accept raw LaTeX strings. That way

you can just use regular LaTeX strings when something is not supported directly

by the library.

##### Unescaping Strings[¶](#unescaping-strings "Permalink to this headline")

Using regular LaTeX strings may not be as simple as is seems though, because by

default almost all strings are escaped. This is done for security reasons and

to make sure valid LaTeX code will be generated at all times. However, there

are cases where raw LaTeX strings should just be used directly in the document.

This is why the `NoEscape` string type exists. This is just a subclass of

[`str`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)"), but it will not be escaped. One important thing to note about this class

is that appending a `NoEscape` type string to a regular string results in

a regular string, since one type has to be chosen and the most conservative

approach is taken.

Another way to make sure strings are not escaped is by setting the

`escape` attribute to [`False`](https://docs.python.org/3/library/constants.html#False "(in Python v3.6)") on the class that is the container

of the string. Keep in mind though that any strings that are added to that

object will not be escaped when doing this. So, only use this method for

objects that don’t contain possibly unsafe strings.

### Examples[¶](#examples "Permalink to this headline")

The examples below show some of the different uses of PyLaTeX. They show how to

use some of the modules. For all the uses and modules please see the [API reference](index.html#document-api).

### API reference[¶](#api-reference "Permalink to this headline")

This section shows all of classes and functions this library exposes. The most

important thing to remember when looking at the documentation, is that this

library uses subclassing extensively. That is why you should always look at the

parent classes if it seems like the class you are looking at is missing

methods.

### Frequently Asked Questions[¶](#frequently-asked-questions "Permalink to this headline")

#### How do I...[¶](#how-do-i "Permalink to this headline")

... “Rerun LaTeX”

Sometimes the compiler will not be able to complete the document in one pass.

In this case it will instruct you to “Rerun LaTeX” via the log output

In order to deal with this, you need to make sure that [latexmk](http://personal.psu.edu/jcc8//software/latexmk-jcc) is installed.

Pylatex will detect and use it automatically.

For Ubuntu and other Debian based systems:

```

sudo apt-get install latexmk

```

### Change Log[¶](#change-log "Permalink to this headline")

All notable changes to this project will be documented on this page. This

project adheres to [Semantic Versioning](http://semver.org/).

#### [Unreleased](https://github.com/JelteF/PyLaTeX/compare/v1.3.0...HEAD) - [docs](../latest/)[¶](#unreleased-docs "Permalink to this headline")

See these docs for changes that have not yet been released and are

only present in the development version.

This version might not be stable, but to install it use:

```

pip install git+https://github.com/JelteF/PyLaTeX.git

```

#### [1.3.0](https://github.com/JelteF/PyLaTeX/compare/v1.2.1...1.3.0) - [docs](../v1.3.0/) - 2017-05-19[¶](#docs-2017-05-19 "Permalink to this headline")

##### Added[¶](#added "Permalink to this headline")

* Longtables now have end\_foot() and end\_last\_foot() functions.

* Added TikZ basic drawing functions for nodes and paths, with minimal coordinate support.

* More section levels `Part`, `Chapter`, `Paragraph`, `Subparagraph`.

* Add label and cross reference support.

##### Changed[¶](#changed "Permalink to this headline")

* More descriptive error when no compatible LaTeX compiler was found.

##### Fixed[¶](#fixed "Permalink to this headline")

* `latex\_name` is now fixed for the `Document` class. This way you can

safely subclass it.

* Uncertain quantity objects work again.

#### [1.2.1](https://github.com/JelteF/PyLaTeX/compare/v1.2.0...v1.2.1) - [docs](../v1.2.1/) - 2017-05-19[¶](#id1 "Permalink to this headline")

##### Fixed[¶](#id2 "Permalink to this headline")

* Filenames with a `~` (tilde) in them now also work as figure paths. This

caused issues when using temp directories on Windows.

#### [1.2.0](https://github.com/JelteF/PyLaTeX/compare/v1.1.1...v1.2.0) - [docs](../v1.2.0/) - 2017-05-06[¶](#docs-2017-05-06 "Permalink to this headline")

##### Added[¶](#id3 "Permalink to this headline")

* Escape flag to `Math` container

* `\_star\_latex\_name` attribute of `LatexObject` to append a star

* `Alignat` math environment

* `Figure.add\_plot` method looks for extension in kwargs

* `Tabu` and `LongTabu` environments learn ‘spread’ and ‘to’ syntax to control their width.

##### Fixed[¶](#id4 "Permalink to this headline")

* Escape `[` and `]` (left and right bracket).

* Allow mappers of `dumps\_list` to return a `LatexObject`.

* Section numbering default behaviour fixed

* Setter method for `escape` property added

#### [1.1.1](https://github.com/JelteF/PyLaTeX/compare/v1.1.0...v1.1.1) - [docs](../v1.1.1/) - 2016-12-10[¶](#docs-2016-12-10 "Permalink to this headline")

##### Changed[¶](#id5 "Permalink to this headline")

* Installs from git now get installed as a special version based on the commit.

This is done by using versioneer.

* Releases can be done with much less manual work for the maintainer in the

future.

##### Fixed[¶](#id6 "Permalink to this headline")

* Install now works on python 3.6+

* Pypi installs will not fail anymore for python 2.7, when `3to2` and

`future` were installed.

#### [1.1.0](https://github.com/JelteF/PyLaTeX/compare/v1.0.0...v1.1.0) - [docs](../v1.1.0/) - 2016-12-09[¶](#docs-2016-12-09 "Permalink to this headline")

##### Changed[¶](#id7 "Permalink to this headline")

* Allow overriding of the default numbering of `Section` class.

* `Parameters` now unpacks a dict as keyword arguments when passed a single

dictionary as argument.

* Escape generated `\n` characters by PyLaTeX by placing a `%` sign in

front of them.

* For better readability let `escape\_latex` change a newline to `\\%\n`

instead of simply `\\`.

* `Document` packages now get propagated from the preamble elements as well.

* Changed `Figure.add\_image` to add a `StandAloneGraphic`

* `Tabular.add\_row` now accepts a list of mappers

* `Tabular.add\_row` now accepts cells as arguments, so they don’t have to be

wrapped in a [`list`](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.6)") or [`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.6)") anymore.

* Changed from using `$$ ... $$` for displaymath to using `\[ ... \]`.

##### Added[¶](#id8 "Permalink to this headline")

* Add the `textcomp` package by default. This way some special glyphs, like

the Euro (€) Symbol can be used in the source.

* `Quantity` got a new `options` keyword argument and learned to handle

uncertain quantities.

* Added `PageStyle` class to support the creation of various page styles. In

addition to this class `Head` and `Foot` were added for creating unique

headers and footers within the page styles. A `simple\_page\_number` function

was also added for easy displaying of a simple page number.

* Added a new type of container `ContainerCommand` for supporting commands

with data.

* Added new options to the `Document` constructor: `geometry\_options` (a

list of options for the geometry package), `document\_options` (a list of

options to place in the document class), `indent` (an option to select

whether the documents elements are indented), `page\_numbers` (an option to

choose whether to use page numbers or not), `font\_size` (the font size to

set at the beggining of the document).

* Added several new methods to the `Document`: `change\_page\_style`,

`change\_document\_style`, `add\_color`, `change\_length`,

`set\_variable`.

* Added a new `position` package with the following classes: `Center` (an

environment with centered content), `FlushLeft` (an environment with left

aligned content), `FlushRight` (an environment with right aligned content),

`MiniPage` (a portion of the document with a certain width and height),

`TextBlock` (a portion of the document for which the position can be selected

using x,y coordinates), `VerticalSpace` and `HorizontalSpace` (add space of

a certain size by using vspace and hspace)

* Added `StandAloneGraphic` to support the creation of images outside of

figure environments.

* Added the ability to change the `row\_height` of a table within the

`Tabular` constructor.

* Added a new type of table `Tabularx`.

* Added the option to select a color when adding an hline or adding a row to

any `Tabular` environment.

* Added the ability to add your own column types through the `ColumnType`

class.

* Added the ability to end the header of a `LongTable` which repeats on every

consecutive page.

* Added the ability to choose the enumeration symbol in a list using the

`enumeration\_symbol` keyword argument of `Enumerate`.

* Added a `pylatex.basic` module with the following commands: `NewLine`,

`NewPage`, `LineBreak`, `HFill`.

* Added several environments to `pylatex.basic`: `HugeText`, `LargeText`,

`MediumText`, `SmallText`, `FootnoteText`, `TextColor`.

* `Tabular` can now have a width specified to override the calculated width

based on the `table\_spec` argument.

* Default configuration for certain options can be overwritten with the new

`pylatex.config` module.

* Add support for booktabs tables, which look nicer than normal tables.

* Add support for the microtype package.

##### Fixed[¶](#id9 "Permalink to this headline")

* Setting the `lmodern` keyword argument of `Document` to false will not

cause invalid LaTeX code anymore.

* `Quantity` now correctly splits prefix and unit into seperate commands.

* `Quantity` can now handle Celsius.

* `Package` instances now actually get deduplicated.

#### [1.0.0](https://github.com/JelteF/PyLaTeX/compare/v0.8.0...v1.0.0) - [docs](../v1.0.0/) - 2015-11-25[¶](#docs-2015-11-25 "Permalink to this headline")

This realease brings some great changes. The whole package has been refactored

and actual documentation has been added. Because of this, things have been

moved an renamed. One of the most notable changes is that all normal text is

now escaped by default.

##### Changed[¶](#id10 "Permalink to this headline")

* The base\_classes submodule has been split into multiple sub-submodules.

* The old baseclasses have been renamed as well. They now have easier names that

better show their purpose.

* The command and parameters submodules have been merged into one command

submodule in the base\_classes submodule.

* The numpy classes have been moved to the math submodule.

* For all of the previous changes the old submodules and names should still work

during the transition period, but they will be removed before the final

release.

* The `Plt` class has been merged with the `Figure` class. Its

`add\_plot` method also doesn’t take a plt argument anymore. The plt

module is now imported when the `add\_plot` method is used. This also

allows for adding plots in the `SubFigure` class.

* Compiling is more secure now and it doesn’t show output unless an error occurs

or explicitly specified.

* The internal method `propegate\_packages` has been spelled correctly and made

“internal” by adding an underscore in front of the name, resulting in

`\_propagate\_packages`

* The default allignment of a multicolumn is not `c` instead of `|c|`, since

vertical lines in tables are ugly most of the time.

* Make the list method of `Parameters` a private method.

* Make the `get\_table\_width` function private.

* Make `width` and `placement` keyword only arguments for the

`add\_plot` method.

* The old `Table` class is renamed to `Tabular`. A new `Table` class has

been created that represents the `table` LaTeX environment, which can be

used to create a floating table.

* Fixed a bug in the `Document` class, that lead to an error if a filepath

without basename was provided.

* Fixed the testall.sh script such that sphinx and nosetests get called with

the correct python version.

* The graphics submodule has been renamed to figure.

* The pgfplots submodule has been renamed to tikz.

* Rename the `seperate\_paragraph` keyword argument to the correctly spelled

`separate\_paragraph`.

* The `container\_name` attribute has been changed to

`latex\_name` so it can be used more than containers. By default

it is still the lowercase version of the classname. To change the default for

a class you should set `\_latex\_name`

* Made `Document.select\_filepath` private.

* `Container` now has a `dumps\_content` method, which dumps it

content instead of a dumps method. This allows to override just that method

when subclassing `Environment` so you can do dump in some special inside the

environment, while still keeping the `\begin` and `\end` stuff provided

by `Environment`.

* When subclassing a class and special LaTeX packages are needed, you now have

to specify the packages class attribute instead of passing packages along

with the `\_\_init\_\_` method.

* Content of subclasses of `Container` is now automatically escaped. Content

of `Arguments` or `Options` is not escaped by default.

* Made `separate\_paragraph`, `begin\_paragraph` and

`end\_paragraph` class attributes instead of instance

attributes.

* The default of the `filepath` argument for the `Document.generate\_pdf` and

`Document.generate\_tex` have been changed to [`None`](https://docs.python.org/3/library/constants.html#None "(in Python v3.6)"). The response to the

default is not changed, so this is a fairly invisible change.

* Moved `separate\_paragraph`, `begin\_paragraph` and

`end\_paragraph` attributes to `LatexObject`.

* Use `latexmk` to compile to pdf when available, otherwise fallback to

`pdflatex`.

* Change the order of arguments of the `Axis` constructor.

* Tables like `Tabular` now raise an exception when rows with wrong size are

added

* Made lots of keyword arguments keyword only arguments. This was needed to

make it easy to keep the API the same in the future.

* Removed the submodules `pylatex.parameters`, `pylatex.command` and

`pylatex.numpy`. The content of the first two was moved to

`pylatex.base\_classes.command` and the content of the last one was moved to

`pylatex.math`.

##### Removed[¶](#removed "Permalink to this headline")

* The add `add\_multicolumn` and `add\_multirow` methods on tabular classes

are removed in favor of the much more robust and easier to use `MultiRow`

and `MultiColumn` classes.

* Removed unused `name` argument of the `Matrix` class.

* Removed base keyword argument of the `Package` class. `Command` should be

used when changing of the base is needed.

* Removed the `title`, `author`, `date` and `maketitle` arguments from

the `Document` constructor. They were from a time when it was not possible

to change the preamble, which is now very easy. They are not so commonly used

that they should be part of the main `Document` object.

* Removed useless list class constructor arguments for list\_spec and pos. These

were probably copied from the `Tabular` class.

##### Added[¶](#id11 "Permalink to this headline")

* Lots of documentation!!!!!

* A float environment base class.

* An unfinished Quantity class that can be used in conjunction with the

quantitities package. <https://pythonhosted.org/quantities/>

* Allow supplying a mapper function to dumps\_list and the add\_row method for

tabular like objects.

* An `extra\_arguments` argument to `Command`. See docs for description.

* Add `CommandBase`, which can be easily subclassed for a command that is used

more than once.

* Add `NoEscape` string class, which can be used to make sure a raw LaTeX

string is not escaped.

* A `\_\_repr\_\_` method, so printing LaTeX objects gives more useful

information now.

#### [0.8.0](https://github.com/JelteF/PyLaTeX/compare/v0.7.1...v0.8.0) - 2015-05-23[¶](#id12 "Permalink to this headline")

##### Added[¶](#id13 "Permalink to this headline")

* List classes (enumerate, itemize, description)

* Arguments for plt.savefig

* SubFigure class for use with subcaption package

* Command line argument for ./testall.sh to supply a custom python command

* The generate\_tex method is now usable in every class, this makes making

snippets even easier.

* MultiColumn and MultiRow classes for generalized table layouts.

##### Changed[¶](#id14 "Permalink to this headline")

* BaseLaTeXNamedContainer now uses the name of the class as the default

container\_name

* The `Table` object is going to be deprecated in favor of the better named

`Tabular` object. This will take a couple of releases.

* Allow the data keyword argument of containers to be a single item instead of a

list. If this is the case it will be wrapped in a list on initialization.

##### Fixed[¶](#id15 "Permalink to this headline")

* Propagate packages recursively add packages of sub containers

* Make cleanup of files Windows compatible

* Filenames can be paths (`foo/bar/my\_pdf`).

* Replace `filename` by `filepath` in the names of the arguments.

* Matplotlib support now uses the tmpfile module, this fixes permission issues

with the badly previously badly located tmp directory.

* The temp directory is only removed in generate\_pdf when cleaning is

enabled

#### [0.7.1](https://github.com/JelteF/PyLaTeX/compare/v0.7.0...v0.7.1) - 2015-03-21[¶](#id16 "Permalink to this headline")

##### Added[¶](#id17 "Permalink to this headline")

* Contributing guidelines.

##### Changed[¶](#id18 "Permalink to this headline")

* The non keyword argument for filename is now called path instead of filename

to show it can also be used with paths.

* Travis now checks for Flake8 errors.

##### Fixed[¶](#id19 "Permalink to this headline")

* Fix a bug in Plt and one in fix\_filename that caused an error when using them

with some filenames (dots in directories and a file without an extension)

#### [0.7.0](https://github.com/JelteF/PyLaTeX/compare/v0.6.1...v0.7.0) - 2015-03-17[¶](#id20 "Permalink to this headline")

##### Added[¶](#id21 "Permalink to this headline")

* Matplotlib support

* Quite a bit of basic docstrings

##### Changed[¶](#id22 "Permalink to this headline")

* Filenames should now be specified to the

`generate\_pdf`/`generate\_tex` methods of document. If

this is not done the `default\_filename` attribute will be used.

##### Fixed[¶](#id23 "Permalink to this headline")

* Fix a lot of bugs in the `escape\_latex` function

#### [0.6.1](https://github.com/JelteF/PyLaTeX/compare/v0.6...v0.6.1) - 2015-01-11[¶](#id24 "Permalink to this headline")

##### Added[¶](#id25 "Permalink to this headline")

* Travis tests

##### Fixed[¶](#id26 "Permalink to this headline")

* Bug in VectorName

#### [0.6](https://github.com/JelteF/PyLaTeX/compare/v0.5...v0.6) - 2015-01-07[¶](#id27 "Permalink to this headline")

##### Added[¶](#id28 "Permalink to this headline")

* Figure class

* Command and Parameter classes

* `with` statement support

#### [0.5](https://github.com/JelteF/PyLaTeX/compare/v0.4.2...v0.5) - 2014-06-02[¶](#id29 "Permalink to this headline")

##### Added[¶](#id30 "Permalink to this headline")

* Python 2.7 support

#### [0.4.2](https://github.com/JelteF/PyLaTeX/compare/v0.4.1...v0.4.2) - 2014-03-18[¶](#id31 "Permalink to this headline")

##### Added[¶](#id32 "Permalink to this headline")

* More table types

#### [0.4.1](https://github.com/JelteF/PyLaTeX/compare/68ddef6bc43a5dff42105c3a38068d87d99d049f...v0.4.1) - 2014-01-29[¶](#id33 "Permalink to this headline")

##### Added[¶](#id34 "Permalink to this headline")

* Partial experimental support for multicol/multirow

##### Fixed[¶](#id35 "Permalink to this headline")

* Fix package delegation with duplicate packages

### How to contribute[¶](#how-to-contribute "Permalink to this headline")

First of all, if anything is incorrect or something is missing on this page (or

any other for that matter), please send in a pull request. It is important that

setting up the development environment is as painless as possible.

#### Setting up the development environment[¶](#setting-up-the-development-environment "Permalink to this headline")

Unfortunately there are quite some steps involved in setting up a development

environment. If you don’t want to do this and know how Vagrant works, see the

bottom of this section on how to use that instead.

##### OS specific dependencies[¶](#os-specific-dependencies "Permalink to this headline")

Some dependencies are OS specific. Ofcourse you need to have LaTeX installed,

but that also comes in some different packages on most systems.

For Ubuntu and other Debian based systems:

```

sudo apt-get install python3 python3-dev virtualenv \

    texlive-pictures texlive-science texlive-latex-extra \

    imagemagick

```

##### Getting the source code[¶](#getting-the-source-code "Permalink to this headline")

You need your own fork of the [Github repository](https://github.com/JelteF/PyLaTeX) by using the Github fork button. You will

then need to clone your version of the repo using the normal way, something

like this:

```

git clone git@github.com:YourUserName/pylatex

cd pylatex

```

Make your own branch for your specific feature or fix (don’t do this just on

master):

```

git checkout -b your-nice-feature

```

##### Python environment setup[¶](#python-environment-setup "Permalink to this headline")

This method will use a virtual environment, this is the easiest way to get all

the dependencies.

1. Create a virtualenv by running:

```

virtualenv venv -p python3

```

2. Activate it by running (you should do this whenever you start working on

your changes):

```

. venv/bin/activate

```

3. Install all the development dependencies inside the virtual environment by

running:

```

pip install -r dev_requirements.txt

```

##### Vagrant support[¶](#vagrant-support "Permalink to this headline")

This might be an easier way to obtain a development environment, but the script

is not very well maintained and might not work anymore. If everything goes as

planned Vagrant will launch and configure a small virtual machine with all

necessary tools for you, so that you can start working with PyLaTeX right away.

With Vagrant already installed, you can start the virtual machine with

`$ vagrant up` and then use `$ vagrant ssh` to ssh into it. Your source

files will be located under `/vagrant`.

To run all unit tests and build the documentation run

`$ ./testall.sh -p python3 -c` from that directory.

You can download or read more about Vagrant on <https://www.vagrantup.com/>.

#### Some tips before starting[¶](#some-tips-before-starting "Permalink to this headline")

1. Look at the code that is already there when creating something new, for

instance the classes for tables.

2. To learn how to squash commits, read this [blog](http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html).

Ignore the word of caution, since that only applies to main repositories on

which people base their own work. You can do this when you have a couple of

commits that could be merged together. This mostly happens when you have

commits that fix a typo or bug you made in a pull request and you fix that

in a new commit.

#### Some rules[¶](#some-rules "Permalink to this headline")

There are two things that are needed for every pull request:

1. Run the `testall.sh` script before making a pull request to check if you

didn’t break anything.

2. Follow the **PEP8** style guide and make sure it passes pyflakes (this is

also tested with the `testall.sh` script).

These are also tested for by Travis, but please test them yourself as well.

Depending on your type of changes some other things are needed as well.

1. If you add new arguments, function or classes, add them to

`tests/args.py` without forgetting to name the arguments. That way it is

easy to see when the external API is changed in the future.

2. Change docstrings when necessary. For instance when adding new arguments or

changing behaviour.

3. If you fix something, add a **test** so it won’t break again.

4. If your change is user facing, add it to the **changelog** so it will be

mentioned in the next release. Its location is at

`docs/source/changelog.rst`.

5. If you add something new, show it off with an **example**. If you don’t do

this, I will probably still merge your pull request, but it is always nice

to have examples of features.

Indices[¶](#indices "Permalink to this headline")

-------------------------------------------------

* [Index](genindex.html)

* [Module Index](py-modindex.html)

