package lwt

  1. Overview
  2. Docs
Promises and event-driven I/O

Install 

dune-project
 Dependency

github.com Readme MIT License Edit opam file Versions (27)

Authors

  1. J
    Jérôme Vouillon
  2. J
    Jérémie Dimino

Maintainers

  1. R
    Raphaël Proust <code@bnwr.net>
  2. Anton Bachin

Sources

6.0.0-alpha00.tar.gz
md5=8a88c5d5fcb01d179bbb12e6b6888dca
sha512=bfecd3fa0a3461a3368bd7724e2fce7a751ba3899d590d5b08bc4257b058ca34ec25de1a3ead6585528afe77c6ca6db1c3e2d2421d6a773c845ef091472d2ed9

Description

A promise is a value that may become determined in the future.

Lwt provides typed, composable promises. Promises that are resolved by I/O are resolved by Lwt in parallel.

Meanwhile, OCaml code, including code creating and waiting on promises, runs in a single thread by default. This reduces the need for locks or other synchronization primitives. Code can be run in parallel on an opt-in basis.

Published: 24 Jul 2025

README

Lwt

version GitHub Actions status

Lwt is a concurrent programming library for OCaml. It provides a single data type: the promise, which is a value that will become determined in the future. Creating a promise spawns a computation. When that computation is I/O, Lwt runs it in parallel with your OCaml code.

OCaml code, including creating and waiting on promises, is run in a single thread by default, so you don't have to worry about locking or preemption. You can detach code to be run in separate threads on an opt-in basis.

Here is a simplistic Lwt program which requests the Google front page, and fails if the request is not completed in five seconds:

open Lwt.Syntax

let () =
  let request =
    let* addresses = Lwt_unix.getaddrinfo "google.com" "80" [] in
    let google = Lwt_unix.((List.hd addresses).ai_addr) in

    Lwt_io.(with_connection google (fun (incoming, outgoing) ->
      let* () = write outgoing "GET / HTTP/1.1\r\n" in
      let* () = write outgoing "Connection: close\r\n\r\n" in
      let* response = read incoming in
      Lwt.return (Some response)))
  in

  let timeout =
    let* () = Lwt_unix.sleep 5. in
    Lwt.return None
  in

  match Lwt_main.run (Lwt.pick [request; timeout]) with
  | Some response -> print_string response
  | None -> prerr_endline "Request timed out"; exit 1

(* ocamlfind opt -package lwt.unix -linkpkg example.ml && ./a.out *)

In the program, functions such as Lwt_io.write create promises. The let* ... in construct is used to wait for a promise to become determined; the code after in is scheduled to run in a "callback." Lwt.pick races promises against each other, and behaves as the first one to complete. Lwt_main.run forces the whole promise-computation network to be executed. All the visible OCaml code is run in a single thread, but Lwt internally uses a combination of worker threads and non-blocking file descriptors to resolve in parallel the promises that do I/O.


Overview

Lwt compiles to native code on Linux, macOS, Windows, and other systems. It's also routinely compiled to JavaScript for the front end and Node by js_of_ocaml.

In Lwt,

  • The core library Lwt provides promises...
  • ...and a few pure-OCaml helpers, such as promise-friendly mutexes, condition variables, and mvars.
  • There is a big Unix binding, Lwt_unix that binds almost every Unix system call. A higher-level module Lwt_io provides nice I/O channels.
  • Lwt_process is for subprocess handling.
  • Lwt_preemptive spawns system threads.
  • The PPX syntax allows using all of the above without going crazy!
  • There are also some other helpers, such as Lwt_react for reactive programming. See the table of contents on the linked manual pages!

Installing

  1. Use your system package manager to install a development libev package. It is often called libev-dev or libev-devel.
  2. opam install conf-libev lwt

Documentation

We are currently working on improving the Lwt documentation (drastically; we are rewriting the manual). In the meantime:

  • The current manual can be found here.
  • Mirage has a nicely-written Lwt tutorial.
  • An example of a simple server written in Lwt.
  • Concurrent Programming with Lwt is a nice source of Lwt examples. They are translations of code from the excellent Real World OCaml, but are just as useful if you are not reading the book.

Note: much of the current manual refers to 'a Lwt.t as "lightweight threads" or just "threads." This will be fixed in the new manual. 'a Lwt.t is a promise, and has nothing to do with system or preemptive threads.


Contact

Open an issue, visit Discord chat, ask on discuss.ocaml.org, or on Stack Overflow.

Release announcements are made on discuss.ocaml.org. Watching the repo for "Releases only" is also an option.


Contributing

  • CONTRIBUTING.md contains tips for working on the code, such as how to check the code out, how review works, etc. There is also a high-level outline of the code base.
  • Ask us anything, whether it's about working on Lwt, or any question at all about it :)
  • The documentation always needs proofreading and fixes.
  • You are welcome to pick up any other issue, review a PR, add your opinion, etc.
  • Any feedback is welcome, including how to make contributing easier!

Libraries to use with Lwt

Dependencies (5)

  1. ocplib-endian
  2. dune-configurator
  3. cppo build & >= "1.1.0"
  4. ocaml >= "4.08"
  5. dune >= "2.7"

Dev Dependencies (3)

  1. bisect_ppx with-test
  2. odoc with-doc & >= "2.3.0"
  3. ocamlfind dev & >= "1.7.3-1"

  1. 0install >= "2.15.1"
  2. aches-lwt
  3. activitypub
  4. albatross
  5. alcotest-lwt
  6. alcotest-mirage
  7. ambient-context-lwt
  8. amqp-client >= "1.1.0"
  9. amqp-client-lwt
  10. angstrom-lwt-unix >= "0.11.0"
  11. anthill
  12. anycache-lwt
  13. archi-lwt
  14. arp
  15. awa-mirage
  16. aws-lwt
  17. aws-s3-lwt < "4.4.0" | >= "4.8.1"
  18. awsm-lwt
  19. azure-cosmos-db
  20. balancer
  21. bastet_lwt
  22. bimage-lwt
  23. bistro
  24. brisk-reconciler
  25. brozip
  26. builder
  27. builder-web
  28. bun >= "0.3.3"
  29. cachet-lwt
  30. calculon
  31. caldav
  32. camltc
  33. canary
  34. capnp-rpc-lwt < "2.0"
  35. capnp-rpc-unix < "2.1"
  36. caqti-lwt
  37. caqti-mirage
  38. carton < "1.0.0"
  39. carton-git
  40. carton-lwt
  41. catala-format >= "0.2.0"
  42. cf-lwt
  43. chamelon
  44. chamelon-unix
  45. chamo
  46. charrua-client
  47. charrua-unix
  48. chess_com_api
  49. clz
  50. cmdtui-lambda-term
  51. coap
  52. coap-server-lwt
  53. cohttp-curl-lwt
  54. cohttp-lwt
  55. cohttp-lwt-jsoo
  56. cohttp-lwt-unix
  57. cohttp-mirage
  58. cohttp-server-lwt-unix
  59. comby
  60. comby-semantic
  61. conan-lwt
  62. conduit-lwt
  63. conduit-lwt-unix
  64. cowabloga
  65. crunch
  66. cstruct-lwt
  67. csv-lwt
  68. ctypes >= "0.15.0" & < "0.21.1"
  69. ctypes-foreign >= "0.21.1"
  70. curl_lwt
  71. current
  72. current-albatross-deployer
  73. current_docker
  74. current_examples
  75. current_git
  76. current_github
  77. current_gitlab
  78. current_ocluster
  79. current_rpc
  80. current_slack
  81. current_web
  82. DkSDKFFIOCaml_Std
  83. dap
  84. data-encoding < "0.1.1"
  85. devkit >= "1.2"
  86. distributed-lwt
  87. dkim-bin < "0.8.0"
  88. dkim-lwt-unix
  89. dkim-mirage
  90. dlm
  91. dns-certify
  92. dns-cli
  93. dns-client < "7.0.3"
  94. dns-client-lwt
  95. dns-client-mirage
  96. dns-forward
  97. dns-forward-lwt-unix
  98. dns-lwt
  99. dns-mirage
  100. dns-resolver
  101. dns-server
  102. dns-stub
  103. dnssd
  104. docker_hub
  105. docteur >= "0.0.2"
  106. docteur-solo5
  107. docteur-unix >= "0.0.5"
  108. doi2bib
  109. dream
  110. dream-httpaf
  111. dream-pure
  112. dream-serve
  113. dropbox
  114. dune >= "3.17.2"
  115. dune-rpc-lwt
  116. earlybird
  117. elasticsearch-cli
  118. emoji >= "2.0.0"
  119. equinoxe
  120. ethernet
  121. ez_api >= "1.2.0"
  122. ezcurl-lwt
  123. ezjs_min < "0.2"
  124. ezjsonm-lwt
  125. ezresto
  126. ezresto-directory >= "0.5"
  127. faraday-lwt
  128. faraday-lwt-unix
  129. fat-filesystem
  130. fiber-lwt
  131. fsevents-lwt
  132. fswatch_lwt
  133. fuseau-lwt
  134. gdbprofiler
  135. git
  136. git-cohttp
  137. git-cohttp-unix
  138. git-kv >= "0.2.0"
  139. git-mirage
  140. git-paf
  141. git-unix >= "3.2.0"
  142. github
  143. github-hooks
  144. github-unix >= "4.4.0"
  145. gitlab-unix
  146. gitlab_pipeline_notifier
  147. gluten-lwt
  148. gluten-lwt-unix < "0.4.0"
  149. gluten-mirage < "0.4.0"
  150. graphql-lwt
  151. gremlin
  152. grpc-lwt
  153. guardian
  154. gufo
  155. h1
  156. h1-lwt-unix
  157. h2-lwt
  158. h2-lwt-unix < "0.10.0"
  159. h2-mirage
  160. happy-eyeballs-lwt
  161. happy-eyeballs-mirage
  162. hidapi-lwt
  163. hiredis >= "0.6"
  164. hl_yaml
  165. hockmd
  166. http-lwt-client
  167. http-mirage-client
  168. http-multipart-formdata >= "2.0.0" & < "3.0.0"
  169. httpaf-lwt-unix
  170. httpun-lwt
  171. httpun-mirage
  172. httpun-ws-lwt
  173. hvsock
  174. i3ipc
  175. influxdb-lwt
  176. inotify >= "2.4"
  177. inquire < "0.3.0"
  178. interface-prime-lwt
  179. ip2location
  180. ip2locationio
  181. ip2whois
  182. ipv6-multicast-lwt
  183. irc-client-lwt
  184. irc-client-lwt-ssl
  185. irc-client-tls
  186. irmin
  187. irmin-bench
  188. irmin-chunk
  189. irmin-cli
  190. irmin-client
  191. irmin-containers
  192. irmin-fs
  193. irmin-git
  194. irmin-graphql
  195. irmin-http
  196. irmin-indexeddb
  197. irmin-layers
  198. irmin-mirage-git
  199. irmin-mirage-graphql
  200. irmin-pack
  201. irmin-server
  202. irmin-test
  203. irmin-unix
  204. irmin-watcher
  205. joolog
  206. jose < "0.9.0"
  207. js_of_ocaml-lwt >= "3.5.0"
  208. jsoo_broadcastchannel
  209. jsoo_storage
  210. jupyter
  211. jupyter-kernel
  212. kafka < "0.5"
  213. kafka_lwt
  214. kappa-library
  215. ke >= "0.5"
  216. kinetic-client
  217. kubecaml
  218. lambda-runtime
  219. lambda-term
  220. lambda_streams_lwt
  221. launchd
  222. ldp
  223. learn-ocaml
  224. learn-ocaml-client
  225. ledgerwallet >= "0.4.0"
  226. letsencrypt
  227. letsencrypt-app
  228. letsencrypt-dns
  229. letters
  230. lichess_api
  231. links >= "0.9.1"
  232. llama
  233. lru_cache
  234. lwt-canceler
  235. lwt-dllist
  236. lwt-exit
  237. lwt-parallel
  238. lwt-pipe
  239. lwt-pipeline
  240. lwt-watcher
  241. lwt_camlp4
  242. lwt_direct
  243. lwt_domain
  244. lwt_eio
  245. lwt_glib
  246. lwt_log
  247. lwt_ppx
  248. lwt_react
  249. lwt_retry
  250. lwt_ssl
  251. mariadb >= "1.2.0"
  252. markup = "0.7.6"
  253. markup-lwt
  254. mdx
  255. mechaml
  256. mehari-lwt-unix
  257. mehari-mirage
  258. memtrace-mirage
  259. metrics-influx
  260. metrics-lwt
  261. metrics-unix
  262. mimic
  263. mindstorm-lwt
  264. mirage < "4.0.0"
  265. mirage-block >= "2.0.1"
  266. mirage-block-ccm
  267. mirage-block-combinators
  268. mirage-block-lwt
  269. mirage-block-partition
  270. mirage-block-ramdisk
  271. mirage-block-solo5
  272. mirage-block-unikraft
  273. mirage-block-unix >= "2.14.2"
  274. mirage-block-xen
  275. mirage-channel >= "4.0.1"
  276. mirage-channel-lwt
  277. mirage-clock-lwt
  278. mirage-clock-unix < "4.2.0"
  279. mirage-console-lwt
  280. mirage-crypto-rng < "0.11.3"
  281. mirage-crypto-rng-lwt
  282. mirage-crypto-rng-mirage
  283. mirage-device >= "2.0.0"
  284. mirage-flow >= "3.0.0"
  285. mirage-flow-combinators
  286. mirage-flow-lwt
  287. mirage-flow-unix
  288. mirage-fs >= "4.0.0"
  289. mirage-fs-lwt
  290. mirage-kv >= "3.0.1"
  291. mirage-kv-lwt
  292. mirage-kv-unix
  293. mirage-net >= "4.0.0"
  294. mirage-net-lwt
  295. mirage-net-macosx
  296. mirage-net-solo5
  297. mirage-net-unikraft
  298. mirage-net-unix
  299. mirage-net-xen
  300. mirage-profile
  301. mirage-protocols >= "7.0.0"
  302. mirage-protocols-lwt
  303. mirage-qubes
  304. mirage-qubes-ipv4
  305. mirage-runtime
  306. mirage-sleep
  307. mirage-solo5
  308. mirage-stack = "3.0.0"
  309. mirage-stack-lwt
  310. mirage-time >= "3.0.0"
  311. mirage-time-lwt
  312. mirage-time-unix
  313. mirage-types-lwt
  314. mirage-unikraft
  315. mirage-unix
  316. mirage-vnetif
  317. mirage-xen
  318. monorobot
  319. moonpool-lwt
  320. mqtt
  321. mrmime >= "0.5.0"
  322. multipart-form-data
  323. multipart_form >= "0.2.0" & < "0.4.0"
  324. multipart_form-cohttp-lwt < "0.6.0"
  325. multipart_form-lwt
  326. mwt
  327. naboris
  328. nbd >= "4.0.3"
  329. nbd-tool
  330. nbd-unix
  331. nocrypto
  332. nottui-lwt
  333. nproc
  334. nsq
  335. obuilder
  336. obus >= "1.2.1"
  337. ocluster
  338. ocluster-api
  339. ocluster-worker
  340. ocplib-resto
  341. ocsigenserver
  342. ocsipersist
  343. ocsipersist-dbm
  344. ocsipersist-lib
  345. ocsipersist-pgsql
  346. ocsipersist-sqlite
  347. octez-distributed-lwt-internal
  348. octez-internal-libs
  349. octez-l2-libs
  350. octez-libs
  351. octez-proto-libs
  352. octez-protocol-compiler
  353. octez-proxy-server
  354. octez-rpc-process
  355. octez-shell-libs
  356. octez-smart-rollup-wasm-benchmark-lib
  357. oframl
  358. ojs_base
  359. omigrate
  360. oneffs
  361. opencage
  362. opentelemetry-client-cohttp-lwt
  363. opentelemetry-cohttp-lwt >= "0.4"
  364. opentelemetry-lwt
  365. opium
  366. opium-graphql
  367. opium_kernel
  368. opomodoro
  369. order-i3-xfce
  370. ordma
  371. oskel >= "0.3.0"
  372. ounit-lwt < "2.2.0"
  373. ounit2-lwt
  374. owork
  375. ozulip
  376. paf
  377. paf-cohttp
  378. passage
  379. pcap-format < "0.5.2"
  380. petrol
  381. pgn_parser
  382. pgx_lwt
  383. pgx_lwt_mirage
  384. pgx_lwt_unix < "2.0"
  385. piaf < "0.2.0"
  386. picos >= "0.3.0" & < "0.5.0"
  387. picos_lwt
  388. picos_meta
  389. plebeia >= "2.0.0"
  390. plotkicadsch
  391. ppx_defer >= "0.4.0"
  392. ppx_deriving_rpc
  393. ppx_rapper_lwt
  394. proc-smaps
  395. prof_spacetime
  396. prometheus
  397. prometheus-app
  398. promise_jsoo_lwt
  399. protocol-9p
  400. protocol-9p-unix
  401. qcow
  402. qcow-stream
  403. qcow-tool
  404. qcow-types
  405. qfs >= "0.5"
  406. quests
  407. rawlink < "2.1"
  408. rawlink-lwt
  409. rdf_json_ld
  410. rdf_lwt
  411. redis-lwt
  412. reparse-lwt
  413. reparse-lwt-unix
  414. resource-pooling
  415. resp
  416. resp-mirage >= "0.10.0"
  417. resp-unix >= "0.10.0"
  418. resto
  419. resto-cohttp-client >= "0.4"
  420. resto-cohttp-self-serving-client
  421. resto-cohttp-server >= "0.4" & < "0.6" | >= "0.9"
  422. resto-directory >= "0.4"
  423. riak
  424. ringo-lwt
  425. river
  426. rock
  427. rpclib-js
  428. rpclib-lwt
  429. SZXX < "4.0.0"
  430. sanddb
  431. scgi
  432. sendmail-lwt
  433. sendmail-mirage
  434. serial
  435. server-reason-react
  436. session-cohttp-lwt
  437. session-cookie-lwt
  438. session-postgresql-lwt
  439. sessions
  440. shared-block-ring
  441. shared-memory-ring-lwt
  442. sherlodoc
  443. sihl < "0.2.0"
  444. slack
  445. slacko
  446. slipshow
  447. smtml >= "0.7.0"
  448. speed
  449. spin < "0.8.0"
  450. spoke
  451. statocaml
  452. stk
  453. stog
  454. swapfs
  455. syguslib-utils
  456. syndic >= "1.4" & < "1.6.0"
  457. tar-mirage
  458. tar-unix
  459. tcpip
  460. telegraml
  461. terminus
  462. testo-lwt
  463. tezos-base >= "16.0"
  464. tezos-clic >= "16.0"
  465. tezos-crypto >= "16.0"
  466. tezos-crypto-dal
  467. tezos-error-monad >= "16.0"
  468. tezos-lwt-result-stdlib
  469. tezos-p2p = "12.3"
  470. tezos-protocol-environment
  471. tezos-proxy >= "17.3"
  472. tezos-stdlib
  473. tezos-stdlib-unix >= "16.0"
  474. tezos-test-helpers >= "12.3"
  475. tezos-wasmer
  476. tezos-webassembly-interpreter-extra
  477. tezt
  478. tidy_email
  479. timmy-lwt
  480. tls >= "0.10.6" & < "0.16.0"
  481. tls-lwt
  482. tls-mirage
  483. tube
  484. tuntap
  485. twirp_cohttp_lwt_unix
  486. uring
  487. uspf
  488. uspf-lwt
  489. uspf-mirage
  490. utop
  491. uwt
  492. vchan
  493. vchan-unix
  494. vchan-xen
  495. vercel
  496. vhd-format-lwt
  497. vmnet
  498. vpnkit
  499. vue-jsoo < "0.3"
  500. wayland < "2.0"
  501. webauthn
  502. xen-evtchn
  503. xen-evtchn-unix
  504. xen-gnt
  505. xen-gnt-unix
  506. xenstore
  507. xenstore-tool
  508. xenstore_transport
  509. xlsx2csv
  510. yocaml_git
  511. yocaml_unix < "2.0.0"
  512. zarr-lwt
  513. zmq-lwt >= "5.2.1"

Conflicts

None

OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct