---
name: "jupytext"
section: "1"
platform: "linux"
package: "python3-jupytext"
version: "1.16.4+ds1-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/jupytext"
---

# jupytext(1)

Jupyter Notebooks as Markdown Documents or Scripts

## NAME

jupytext - Jupyter Notebooks as Markdown Documents or Scripts

## DESCRIPTION

usage: jupytext \[-h\] \[--from INPUT\_FORMAT\] \[--to OUTPUT\_FORMAT\] \[-o OUTPUT\]

-

  \[--update\] \[--set-formats SET\_FORMATS\] \[--sync\] \[--paired-paths\] \[--format-options FORMAT\_OPTIONS\] \[--update-metadata UPDATE\_METADATA\] \[--use-source-timestamp\] \[--warn-only\] \[--test\] \[--test-strict\] \[--stop\] \[--pipe PIPE\] \[--diff\] \[--diff-format DIFF\_FORMAT\] \[--check CHECK\] \[--pipe-fmt PIPE\_FMT\] \[--set-kernel SET\_KERNEL\] \[--execute\] \[--run-path RUN\_PATH\] \[--quiet\] \[--show-changes\] \[--version\] \[--pre-commit\] \[--pre-commit-mode\] \[notebooks ...\]

Jupyter Notebooks as Markdown Documents, Julia, Python or R Scripts

### positional arguments:

- notebooks

  One or more notebook(s). Notebook is read from stdin when this argument is empty. (default: None)

### options:

- **-h**, **--help**

  show this help message and exit

- **--from** INPUT\_FORMAT

  Jupytext format for the input(s). Inferred from the file extension and content when missing. (default: None)

- **--to** OUTPUT\_FORMAT

  The destination format: 'ipynb', 'markdown' or 'script', or a file extension: 'md', 'Rmd', 'jl', 'py', 'R', ..., 'auto' (script extension matching the notebook language), or a combination of an extension and a format name, e.g. md:myst, md:pandoc, md:markdown or py:sphinx, py:hydrogen, py:percent, py:light, py:nomarker. The default format for scripts is the 'light' format, which uses few cell markers (none when possible). Alternatively, a format compatible with many editors is the 'percent' format, which uses '# %%' as cell markers. The main formats (markdown, light, percent) preserve notebooks and text documents in a roundtrip. Use the **--test** and and **--test-strict** commands to test the roundtrip on your files. Read more about the available formats at https://jupytext.readthedocs.io/en/latest/formats.html (default: None)

- **-o** OUTPUT, **--output** OUTPUT

  Destination file. Defaults to the original file, with prefix/suffix/extension changed according to the destination format. Use '-' to print the notebook on stdout. (default: None)

- **--update**

  Preserve the output cells when the destination notebook is an .ipynb file that already exists (default: False)

- **--set-formats** SET\_FORMATS

  Turn the notebook or text document to one or more alternative representations with e.g. '--set-formats ipynb,py:light'. The **--set-formats** option also triggers the creation/update of all paired files (default: None)

- **--sync**, **-s**

  Synchronize the content of the paired representations of the given notebook. Input cells are taken from the file that was last modified, and outputs are read from the ipynb file, if present. (default: False)

- **--paired-paths**, **-p**

  List the locations of the alternative representations for this notebook. (default: False)

- **--format-options** FORMAT\_OPTIONS, **--opt** FORMAT\_OPTIONS

  Set format options with e.g. '--opt comment\_magics=true' or '--opt notebook\_metadata\_filter=-kernelspec'. (default: None)

- **--update-metadata** UPDATE\_METADATA

  Update the notebook metadata with the desired dictionary. Argument must be given in JSON format. For instance, if you want to activate a pairing in the generated file, use e.g. **--update-metadata** '{"jupytext":{"formats":"ipynb,py:light"}}' See also the **--opt** and **--set-formats** options for other ways to operate on the Jupytext metadata. (default: {})

- **--use-source-timestamp**

  Set the modification timestamp of the output file(s) equalto that of the source file, and keep the source file and its timestamp unchanged. (default: False)

- **--warn-only**, **-w**

  Only issue a warning and continue processing other notebooks when the conversion of a given notebook fails (default: False)

- **--test**

  Test that the notebook is stable under a round trip conversion, up to the expected changes (default: False)

- **--test-strict**

  Test that the notebook is strictly stable under a round trip conversion (default: False)

- **--stop**, **-x**

  In **--test** mode, stop on first round trip conversion error, and report stack traceback (default: False)

- **--pipe** PIPE

  Pipe the text representation (in format **--pipe-fmt**) of the notebook into another program, and read the notebook back. For instance, reformat your notebook with: 'jupytext notebook.ipynb **--pipe** black' If you want to reformat it and sync the paired representation, execute: 'jupytext notebook.ipynb **--sync** **--pipe** black' In case the program that you want to execute does not accept pipes, use {} as a placeholder for a temporary file name into which jupytext will write the text representation of the notebook, e.g.: jupytext notebook.ipynb **--pipe** 'black {}' (default: None)

- **--diff**, **-d**

  Show the differences between (the inputs) of two notebooks (default: False)

- **--diff-format** DIFF\_FORMAT

  The text format used to show differences in **--diff** (default: None)

- **--check** CHECK

  Pipe the text representation (in format **--pipe-fmt**) of the notebook into another program, and test that the returned value is non zero. For instance, test that your notebook is pep8 compliant with: 'jupytext notebook.ipynb **--check** flake8' or run pytest on your notebook with: 'jupytext notebook.ipynb **--check** pytest' In case the program that you want to execute does not accept pipes, use {} as a placeholder for a temporary file name into which jupytext will write the text representation of the notebook, e.g.: jupytext notebook.ipynb **--check** 'pytest {}' (default: None)

- **--pipe-fmt** PIPE\_FMT

  The format in which the notebook should be piped to other programs, when using the **--pipe** and/or **--check** commands. (default: auto:percent)

- **--set-kernel** SET\_KERNEL, **-k** SET\_KERNEL

  Set the kernel with the given name on the notebook. Use '--set-kernel -' to set a kernel matching the current environment on Python notebooks, and matching the notebook language otherwise (get the list of available kernels with 'jupyter kernelspec list') (default: None)

- **--execute**

  Execute the notebook with the given kernel. In the **--pre-commit-mode**, the notebook is executed only if a code cell changed, or if some execution outputs are missing or not ordered. (default: False)

- **--run-path** RUN\_PATH

  Execute the notebook at the given path (defaults to the notebook parent directory) (default: None)

- **--quiet**, **-q**

  Quiet mode: do not comment about files being updated or created (default: False)

- **--show-changes**

  Display the diff for each output file (default: False)

- **--version**, **-v**

  Show jupytext's version number and exit (default: False)

- **--pre-commit**

  Ignore the notebook argument, and instead apply Jupytext on the notebooks found in the git index, which have an extension that matches the (optional) **--from** argument. (default: False)

- **--pre-commit-mode**

  This is a mode that is compatible with the pre-commit framework. In this mode, **--sync** won't use timestamp but instead will determines the source notebook as the element of the pair that is added to the git index. An alert is raised if multiple inconsistent representations are in the index. It also raises an alert after updating the paired files or outputs if those files need to be added to the index. Finally, filepaths that aren't in the source format you are trying to convert from are ignored. (default: False)