JUPYTEXT(1)

💖 NAME 💖

jupytext — bestie, this is the glow-up your Jupyter notebooks have been waiting for: it saves them as plain text documents or scripts. 👑✨

---

✨ DESCRIPTION ✨

okay so real talk, this is a manual page for jupytext, section 1, living in the User Commands corner of the universe. And the whole vibe is: Jupyter Notebooks as Markdown Documents, Julia, Python or R Scripts. like. iconic. 🌈

Here's the usage, and yes we're showing it in all its glory:

jupytext [-h] [--from INPUT_FORMAT] [--to OUTPUT_FORMAT] [-o OUTPUT]
         [--update] [--set-formats SET_FORMATS] [--sync | --paired-paths |
         --test | --test-strict | --version] [--format-options FORMAT_OPTIONS]
         [--update-metadata UPDATE_METADATA] [--use-source-timestamp]
         [--check-source-is-newer] [--warn-only] [--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] [--pre-commit]
         [--pre-commit-mode] [notebooks ...]

🎀 positional arguments 🎀

• notebooks — one or more notebook(s), bestie. if you leave this argument empty, the notebook gets read from stdin. no cap. (default: None)

💅 options 💅

• -h, --help — show this help message and then dip. that's it, that's the option. (default: n/a)
• --from INPUT_FORMAT — the Jupytext format for the input(s). if it's missing, Jupytext figures it out from the file extension and the content. lowkey psychic of it. (default: None)
• --to OUTPUT_FORMAT — where you're sending it, queen. this can be the destination format: 'ipynb', 'markdown' or 'script', or a file extension: 'md', 'Rmd', 'jl', 'py', 'R', ... — or 'auto' (which picks the script extension matching the notebook language), or even a combo of an extension and a format name, like md:myst, md:markdown, md:pandoc or py:light, py:nomarker, py:percent, py:marimo, py:hydrogen, py:sphinx. The default format for scripts is the 'percent' format, which uses '# %%' as cell markers and is compatible with VS Code and PyCharm. OR, if you're feeling different, you can use the 'light' format, which uses fewer cell markers. The main formats (MyST Markdown, Markdown, percent, light) preserve notebooks and text documents in a roundtrip. use the --test and --test-strict commands to test the roundtrip on your files, fr fr. read more about the available formats at https://jupytext.org/formats/scripts/ — NB: on top of all the extensions listed above, you can also use these: 'clj', 'coco', 'cpp', 'cs', 'do', 'fs', 'fsx', 'go', 'gp', 'groovy', 'hs', 'java', 'jenner', 'js', 'lgt', 'logtalk', 'lua', 'm', 'mac', 'markdown', 'ml', 'mnb', 'myst', 'mystnb', 'pro', 'ps1', 'q', 'qmd', 'r', 'resource', 'robot', 'rs', 'sage', 'sas', 'scala', 'scm', 'sh', 'sos', 'ss', 'tcl', 'ts', 'wolfram', 'xsh'. the range?? unmatched. (default: None)
• -o, --output OUTPUT — the destination file. defaults to the original file, but with the prefix/suffix/extension changed to match whatever destination format you asked for. and if you use '-' it prints the notebook on stdout. cute. (default: None)
• --update — when the destination notebook is an .ipynb file that already exists, this preserves the output cells. we do not throw away your outputs, periodt. (default: False)
• --set-formats SET_FORMATS — turns the notebook or text document into one or more alternative representations, like e.g. '--set-formats ipynb,py:light'. and heads up: 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 get taken from whichever file was last modified, and outputs get read from the ipynb file, if there is one. 💅 (default: False)
• --paired-paths, -p — lists the locations of the alternative representations for this notebook. (default: False)
• --format-options, --opt FORMAT_OPTIONS — set format options, like e.g. '--opt comment_magics=true' or '--opt notebook_metadata_filter=-kernelspec'. (default: None)
• --update-metadata UPDATE_METADATA — updates the notebook metadata with the dictionary you want. the argument MUST be given in JSON format, okay bestie? for instance, if you want to activate a pairing in the generated file, use e.g. --update-metadata '{"jupytext":{"formats":"ipynb,py:light"}}'. also check out the --opt and --set-formats options for other ways to operate on the Jupytext metadata. (default: {})
• --use-source-timestamp — sets the modification timestamp of the output file(s) equal to that of the source file, and keeps the source file and its timestamp unchanged. twin behavior. matching timestamps. 🫶 (default: False)
• --check-source-is-newer — checks that the file given as argument is the most recent of ALL the paired files, and if applicable, also checks that it's newer than the destination file. (default: False)
• --warn-only, -w — if the conversion of a given notebook fails, just issue a warning and keep processing the other notebooks. we do not crash the whole party. (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. no wiggle room. (default: False)
• --stop, -x — in --test mode, stop on the first round trip conversion error and report the stack traceback. (default: False)
• --pipe PIPE — pipes the text representation (in format --pipe-fmt) of the notebook into another program, then reads the notebook back. for instance, reformat your notebook with: 'jupytext notebook.ipynb --pipe black'. and if you want to reformat it AND sync the paired representation, execute: 'jupytext notebook.ipynb --sync --pipe black'. in case the program you want to execute doesn't accept pipes, use {} as a placeholder for a temporary file name that jupytext will write the text representation of the notebook into, e.g.: jupytext notebook.ipynb --pipe 'black {}' (default: None)
• --diff, -d — shows 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 — pipes the text representation (in format --pipe-fmt) of the notebook into another program, and tests 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 you want to execute doesn't accept pipes, use {} as a placeholder for a temporary file name that jupytext will write the text representation of the notebook into, 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, whenever you're using the --pipe and/or --check commands. (default: auto:percent)
• --set-kernel, -k SET_KERNEL — sets 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. (you can get the list of available kernels with 'jupyter kernelspec list') (default: None)
• --execute — executes the notebook with the given kernel. in --pre-commit-mode, the notebook only gets executed 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 (which defaults to the notebook parent directory). (default: None)
• --quiet, -q — quiet mode: do not comment about files being updated or created. shhh. 🤫 (default: False)
• --show-changes — displays the diff for each output file. (default: False)
• --version, -v — shows jupytext's version number and exits. (default: False)
• --pre-commit — ignores the notebook argument, and instead applies Jupytext on the notebooks found in the git index, which have an extension that matches the (optional) --from argument. (default: False)
• --pre-commit-mode — a mode that's compatible with the pre-commit framework. in this mode, --sync won't use timestamp; instead it 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're trying to convert from are ignored. it's giving thorough. (default: False)

---

okay that's the whole thing, bestie, you ate this manual page fr fr 💅✨

this page is from jupytext 1.19.6, dated October 2026, and it's section 1 (JUPYTEXT(1)) of the manual. slay, go forth, and convert your notebooks. 🎀🦋🌸