spark-nlp-workshop is a gallery of runnable Spark NLP notebooks, by domain

Examples, not a framework

spark-nlp-workshop is described as public runnable examples of using John Snow Labs' NLP for Apache Spark, and the project description says it in the plainest possible terms: it showcases notebooks and code showing how to use Spark NLP in Python and Scala.

The distinction matters because Spark NLP itself is a substantial library with its own repository, its own releases, Maven coordinates for the Scala artifact and a PyPI package for the Python side, plus an Anaconda channel. None of that is here. What is here is the worked examples.

So the audience is someone who wants to see a specific pipeline run. A data scientist who needs annotators, a trainer and an evaluator working over their own documents; a developer evaluating whether the library fits before adopting it; a domain team in a regulated field who needs to understand what the annotation stage actually asks of a human. The Slack community channel and the project website are where the library's own documentation lives, and this repository is the companion.

The contribution model tells you how the examples are maintained. If you find any example that is no longer working, the project asks you to create an issue. There is no promise of a fix, and there is no test suite that runs the notebooks in continuous integration. The build badge in the header points at the spark-nlp repository, not at this one, so the examples are not verified by the pipeline that builds the library.

That is the honest framing: a curated gallery, kept by its users, where a stale example is a known failure mode rather than a surprise.

Annotation, training and evaluation, then the domains

The table of contents is organised as a pipeline first and by domain second, and that structure is the fastest way to navigate the repository.

The core Jupyter folder has three subfolders that map to the stages of an NLP project. The annotation folder holds examples of labelling data, which is the step that decides everything downstream and the one where the labelling tooling matters most. The training folder holds the model training examples. The evaluation folder, spelled as eval in the path, holds the evaluation examples, which is where you find out whether the pipeline you built is any good.

The tutorial folder holds a second set of notebooks under an old_generation_notebooks directory, split into jupyter and colab variants. The name is a warning: these are kept for reference rather than as the current path.

The Databricks folder is a third platform specific set, for the people who run Spark on Databricks rather than on a laptop or a cluster.

Beyond those, the repository root is a set of vertical and platform folders. There is finance-nlp, legal-nlp, healthcare-nlp, visual-nlp, generative-ai, nlu and open-source-nlp, which are the domain oriented example sets, and there is products, platforms, java, scala, zeppelin, data and a Spark_NLP_Udemy_MOOC directory, which is a course's material. There is also an agents/ directory, which suggests the newer agent oriented examples, and a patterns.json file at the root, which in a library that supports pattern and template matching is likely a matching pattern file rather than something else.

Two things follow from that inventory. The vertical folders are where the library's hardest questions are asked, because a healthcare annotation workflow has very different requirements from a generic one. And the number of platform specific folders, Databricks, Zeppelin, Colab, SageMaker, means the examples are as much about where Spark runs as about what the pipeline does.

The Python setup, and the versions it pins

The Python setup is a short sequence, and it is the part of the readme most people copy directly:

$ java -version
# should be Java 8 (Oracle or OpenJDK)
$ python3 -m venv .sparknlp-env
$ source .sparknlp-env/bin/activate
# spark-nlp by default is based on pyspark 3.x
$ pip install pyspark==3.1.2
$ pip install spark-nlp

Four decisions are visible there. The library needs a JVM, and the readme specifies Java 8 from either Oracle or OpenJDK. The Python environment is a virtual environment in the project directory, activated for the session. PySpark is pinned to an exact version, 3.1.2, and the comment explains that spark-nlp is based on pyspark 3.x by default. And the library itself is installed by its plain PyPI name.

The pin is the detail to think about. PySpark 3.1.2 is an old point release, and pinning it exactly is what makes the example reproducible, but it also means the local environment you build here is not the environment you would run in production. A team on a current Spark would install a different PySpark and meet whatever incompatibilities that implies, and this readme will not tell them what those are, because the examples were written against the pinned version.

That is not a criticism so much as a fact about how example repositories age. The examples are correct for the environment they were written in, and the environment they were written in is stated in the readme, which is more than most example repositories tell you.

The Scala side does not have a setup block here, and the root scala/ and java/ folders hold the examples for those languages, with the Maven coordinates of the library published under com.johnsnowlabs.nlp for the 2.12 build.

Colab, SageMaker and the setup scripts

Because Spark is a JVM system, running the examples in a browser is not as simple as opening a notebook, and the project solves that with a set of setup scripts.

The Colab setup is a single line, run inside a notebook cell:

# This is only to setup PySpark and Spark NLP on Colab
!wget http://setup.johnsnowlabs.com/colab.sh -O - | bash

The script is hosted by the project rather than living in the repository, which means the Colab path does not depend on a checkout at all, and the tutorial folder has a colab variant of the notebooks to match.

The repository also carries the setup scripts themselves for the other environments, and the names show the coverage. There is colab_setup.sh, jsl_colab_setup.sh, jsl_colab_setup_with_OCR.sh, jsl_sagemaker_setup.sh, jsl_sagemaker_setup_3.0.1.sh and jsl_sagemaker_setup_with_OCR.sh. The with_OCR variants are the interesting ones, since they add OCR to an environment, which is what you need when the input is a document image rather than a text file.

That list is a good map of how the library is actually deployed. A notebook on Colab, a notebook on Databricks, a notebook in a SageMaker training job with OCR enabled, a notebook in a Zeppelin environment, and plain Jupyter on a laptop. OCR matters wherever the documents arrive as scans, and the fact that several setup scripts carry OCR variants shows it is treated as a first-class case here.

The environments are also where the versions diverge. A SageMaker setup script pinned to 3.0.1 is a different Spark generation from the PySpark 3.1.2 in the Python instructions, so a team working across both will be maintaining more than one environment.

What the readme does not tell you

The readme for this repository is short, and the gaps are informative rather than accidental.

There is no version matrix. The Python block pins PySpark 3.1.2 and asks for Java 8, but there is no statement of which Spark NLP version the notebooks were written against, and the pip install of spark-nlp is unpinned, so the library you get is the current release while PySpark is an old pin. Whether those two go together depends on when you run it.

There is no hardware guidance. Spark NLP is a deep learning library, and the examples that train or serve models need a GPU to be pleasant, but the readme says nothing about that.

There is no notebook index. The table of contents lists folders, and each folder has its own notebook names, so finding the one example you want means browsing. A longer readme listing the notebooks with a sentence each would be the single most useful addition to this repository.

And the verification story is absent. The header badges point at the spark-nlp repository for the build and the release, and the Spark NLP PyPI, Maven, Anaconda and download badges describe the library. The workshops' own pipelines are not visible here, which is consistent with the contribution model: broken examples are reported as issues.

None of this makes the repository bad. It makes it a snapshot of working code with a stated environment, which is exactly what a workshop should be. The risk is in treating a notebook as a maintained example rather than as a demonstration of a version.

Licence, cadence and where the real project lives

The licence is the Apache Licence 2.0, with the LICENSE file in the repository root, which is the same licence the library itself uses, so the examples and the code they call are on the same footing for anyone who wants to reuse either.

The maintenance picture is active. The repository is not archived, and the last push was on 2026-10-15, with the root still gaining folders such as generative-ai and agents. There are no GitHub releases, which is normal for a repository of examples, since the artifacts to release are the notebooks, and those are versioned with the commits.

The structure of the wider project matters for context. The library is the separate JohnSnowLabs/spark-nlp repository, with its own build workflow, its release tags, its Maven Central artifact under com.johnsnowlabs.nlp for the 2.12 build, and its PyPI package and Anaconda channel. The workshop is the companion, and the project's website at nlp.johnsnowlabs.com is where the user documentation and examples live as a curated set.

So the natural division of labour for an adopter is this. Read the website documentation to decide whether Spark NLP is the right library. Clone this repository to see the library used on real tasks, in the vertical you work in. And take the library, its versions and its support from the spark-nlp repository, not from here.

The last piece is the data folder and the domain folders, which is where the examples get specific enough to be useful. A finance or legal or healthcare example with its own data and its own labels tells you more about whether the library survives contact with your documents than any of the general notebooks, and it is the place to start if you are evaluating the library for that domain.

Editorial conclusion

spark-nlp-workshop suits a developer learning Spark NLP who wants a working notebook for a specific task rather than a reading exercise, and it suits a domain team in finance, legal or healthcare who needs to see what the pipeline looks like on their own documents before building it. It is the wrong choice if you need supported production code, because the library itself lives in the separate spark-nlp repository and this one has no releases of its own, and a poor match if you want reproducible examples, because the setup instructions pin PySpark to 3.1.2 and the repository's own contribution model is an issue when an example stops working. Before adopting, check the pinned PySpark and Java versions against your own cluster, and confirm the example you want still runs before you build on it.

Frequently asked questions

Official sources

1. Issues
2. JohnSnowLabs/spark-nlp-workshop on GitHub
3. License: Apache-2.0
4. README