How are Pipfile and Pipfile.lock used?

It seems that Pipfile / Pipfile.lock are intended to be replacements for requirements.txt, in the context of Python packaging. There isn't much documentation out there on how these actually work, however. I found an evolving description of pipfile on the PyPi section of the Python website here but it's pretty messy and doesn't explain the semantics of the different sections of the file.

Any pointers on how to understand these files?

The concept behind these files is simple and analogue to other already existing tools, if you have some familiarity with Ruby's Bundler or Node's Npm. Pipenv is both a package and virtual environment management tool that uses the Pipfile and Pipfile.lock files to achieve these goals.

Pipenv handles the virtual environment for you in one default standard way (no more activate and deactivate required). Below, some basics to get you started, see more at pipenv website.

Getting Started

Start using pipenv is easy, in your project folder type...

$ pipenv install

... and if it already has a requirements.txt file, it will generate a Pipfile file with the requirements and a virtual environment folder, otherwise, it will generate an empty Pipfile file. If you disliked or changed your mind about something that you have installed, just type...

$ pipenv uninstall <package>

... and you're good to go. To activate the virtual environment that pipenv already generated, go with...

$ pipenv shell

... and your virtual environment will be activated. To leave the environment...

$ exit

... and you will be back to your original terminal session.

Pipfile

The Pipfile file is intended to specify packages requirements for your Python application or library, both to development and execution. You can install a package by simply using...

$ pipenv install flask

... and it will be added as a dependency for deployment and execution or by using ...

$ pipenv install --dev pytest

... and it will be used as a dependency for development time. In both cases, if you need to be more specific about the package version, as stated in the documentation pipenv makes use of the same version specifiers used by pip. The file syntax is pretty straight forward, as follows.

[[source]] # Here goes your package sources (where you are downloading your packages from).
url = "https://pypi.python.org/simple"
verify_ssl = true
name = "pypi"

[packages] # Here goes your package requirements for running the application and its versions (which packages you will use when running the application).
requests = "*"
flask = "*"
pandas = "*"

[dev-packages] # Here goes your package requirements for developing the application and its versions (which packages you will use when developing the application)
pylint = "*"
wheel = "*"

[requires] # Here goes your required Python version.
python_version = "3.6"

Pipfile.lock

The Pipfile.lock is intended to specify, based on the packages present in Pipfile, which specific version of those should be used, avoiding the risks of automatically upgrading packages that depend upon each other and breaking your project dependency tree.

You can lock your currently installed packages using...

$ pipenv lock

... and the tool will lookup your virtual environment folder to generate the lock file for you automatically, based on the currently installed versions. The file syntax is not as obvious as is for Pipfile , so for the sake of conciseness, it will not be displayed here.

As explained above by @Charles Duffy, it is a direct analog of Gemfile and Gemfile.lock from the Ruby world. See reference below for more details.

Reference: https://medium.com/never-hop-on-the-bandwagon/gemfile-and-gemfile-lock-in-ruby-65adc918b856