Skip to main content

No project description provided

Project description

Extensible and Fault-Tolerant Hyperparameter Management

HParams is a thoughtful approach to configuration management for machine learning projects. It enables you to externalize your hyperparameters into a configuration file. In doing so, you can reproduce experiments, iterate quickly, and reduce errors.


  • Approachable and easy-to-use API
  • Battle-tested over three years
  • Fast with little to no runtime overhead (< 3e-05 seconds) per configured function
  • Robust to most use cases with 100% test coverage and 75 tests
  • Lightweight with only one dependency

PyPI - Python Version Codecov Downloads Build Status License: MIT Twitter: PetrochukM

Logo by Chloe Yeo, Corporate Sponsorship by WellSaid Labs


Make sure you have Python 3. You can then install hparams using pip:

pip install hparams

Install the latest code via:

pip install git+

Oops 🐛

With HParams, you will avoid common but needless hyperparameter mistakes. It will throw a warning or error if:

  • A hyperparameter is overwritten.
  • A hyperparameter is declared but not set.
  • A hyperparameter is set but not declared.
  • A hyperparameter type is incorrect.

Finally, HParams is built with developer experience in mind. HParams includes 13 errors and 6 warnings to help catch and resolve issues quickly.


Add HParams to your project by following one of these common use cases:

Configure Training 🤗

Configure your training run, like so:

from hparams import configurable, add_config, HParams, HParam
from typing import Union

def train(batch_size: Union[int, HParam]=HParam(int)):

class Model():

    def __init__(self, hidden_size=HParam(int), dropout=HParam(float)):

add_config({ 'main': {
    'train': HParams(batch_size=32),
    'Model.__init__': HParams(hidden_size=1024, dropout=0.25),

HParams supports optional configuration typechecking to help you find bugs! 🐛

Set Defaults

Configure PyTorch and Tensorflow defaults to match via:

from torch.nn import BatchNorm1d
from hparams import configurable, add_config, HParams

# NOTE: `momentum=0.01` to match Tensorflow defaults
BatchNorm1d.__init__ = configurable(BatchNorm1d.__init__)
add_config({ 'torch.nn.BatchNorm1d.__init__': HParams(momentum=0.01) })

Configure your random seed globally, like so:

import random
from hparams import configurable, add_config, HParams

random.seed = configurable(random.seed)
add_config({'random.seed': HParams(a=123)})
import config
import random



Experiment with hyperparameters through your command line, for example:

foo@bar:~$ --torch.optim.adam.Adam.__init__ 'HParams(lr=0.1,betas=(0.999,0.99))'
import sys
from torch.optim import Adam
from hparams import configurable, add_config, parse_hparam_args

Adam.__init__ = configurable(Adam.__init__)
parsed = parse_hparam_args(sys.argv[1:])  # Parse command line arguments

Hyperparameter optimization

Hyperparameter optimization is easy to-do, check this out:

import itertools
from torch.optim import Adam
from hparams import configurable, add_config, HParams

Adam.__init__ = configurable(Adam.__init__)

def train():  # Train the model and return the loss.

for betas in itertools.product([0.999, 0.99, 0.9], [0.999, 0.99, 0.9]):
    add_config({Adam.__init__: HParams(betas=betas)})  # Grid search over the `betas`

Track Hyperparameters

Easily track your hyperparameters using tools like Comet.

from comet_ml import Experiment
from hparams import get_config

experiment = Experiment()

Multiprocessing: Partial Support

Export a Python functools.partial to use in another process, like so:

from hparams import configurable, HParam

def func(hparam=HParam()):

partial = func.get_configured_partial()

With this approach, you don't have to transfer the global state to the new process. To transfer the global state, you'll want to use get_config and add_config.

Docs 📖

The complete documentation for HParams is available here.


We've released HParams because a lack of hyperparameter management solutions. We hope that other people can benefit from the project. We are thankful for any contributions from the community.

Contributing Guide

Read our contributing guide to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to HParams.



If you find HParams useful for an academic publication, then please use the following BibTeX to cite it:

author = {Petrochuk, Michael},
title = {HParams: Hyperparameter management solution},
year = {2019},
publisher = {GitHub},
journal = {GitHub repository},
howpublished = {\url{}},

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for hparams, version 0.3.0
Filename, size File type Python version Upload date Hashes
Filename, size hparams-0.3.0-py3-none-any.whl (11.3 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size hparams-0.3.0.tar.gz (12.7 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page